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PREFACE 


MANUAL  OBJECTIVES 

The  purpose  of  this  manual  is  to  provide  all  information  necessary  to 
interface  directly  with  the  I/O  device  drivers  supplied  as  part  of  the 
RSX-llM/M-PLUS  system. 


INTENDED  AUDIENCE 

This  manual  is  intended  for  use  by  experienced  RSX-llM/M-PLUS 
programmers  who  want  to  take  advantage  of  the  time  and/or  space 
savings  which  result  from  direct  use  of  •"he  I/O  drivers.  Readers  are 
expected  to  be  familiar  with  the  information  contained  in  the 
RSX-llM/M-PLUS  Executive  Reference  Manual ,  and  to  have  some  experience 
using  the  Task  Builder  and  either  MACRO-11  or  FORTRAN  programs  and  to 
be  familiar  with  the  manuals  describing  their  use. 


STRUCTURE  OF  THE  DOCUMENT 

Chapter  1  provides  an  overview  of  RSX-llM  input/output  operations.  It 
is  somewhat  tutorial  in  its  approach  in  introducing  the  reader  to  the 
use  of  logical  unit  numbers,  directive  parameter  blocks,  event  flags, 
macro  calls,  etc.  The  discussions  include  the  standard  I/O  functions 
common  to  a  variety  of  devices,  and  summarizes  standard  error  and 
status  conditions  relating  to  completion  cf  I/O  requests. 

Chapters  2  through  23  describe  the  use  of  all  device  drivers  supported 
by  RSX-llM  and/or  RSX-llM-PLUS;  refer  to  the  preceding  Summary  Of 
Technical  Changes  to  determine  which  drivers  are  supported  in  your 
operating  system.   Descriptions  by  chapter  are  as  follows: 


Chapter 
2 


Device  Drivers 

Full-duplex   terminal   communications   line 
interface 

Half-duplex   terminal   communications   line 
interface 


4 

5 
6 
7 
8 


Virtual  terminal  driver 

Disks 

DECtape 

DECtape  II 

Magnetic  tape 
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PREFACE 

Chapter  D«vic«  Drivers 

9  Cassette 

10  Line  printers 

11  Card  reader         • 
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13 


Message-oriented     communications     line 
interfaces 

PCLll    parallel    communications     link 
transmitter  and  receiver 


14  Analog-to-dlgltal  converters 

15  Universal  digital  controller 
Ifi  Laboratory  peripheral  systems 

17  Paper  tape  reader/punch 

18  Industrial  control  subsystems 

19  The  null  device 

20  Graphics  display  terminals 

21  LPAll-K  laboratory  peripheral  accelerator 

22  K-serles  laboratory  peripherals 

23  UNIB'   switch 

bach  of  these  chapters  is  structured  In  similar  fashion  and  focuses  on 
the  following  basic  elements: 

•  Description  of  the  device.  Including  Information  on  physical 
characteristics  such  as  speed,  capacity,  access,  and  usage 

•  Summary  of  standard  functions  supported  by   the  devices  and 
descriptions  of  device-specific  functions 

e  Discussion  of  special  characters,  rarrlage  control  codes,  and 
functional  characteristics.  If  relevant 

•  Summary  of  error  and  status  conditions  '-turned  on  acceptance 
or  rejection  of  I/O  requests 

e  Description  of  programming  hints  for  users  of  the  device  under 
RSX-llM 


• 
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Appendixes  A  through  C  provide  quick   reference  material  on   I/O 
functions  and  status  codes.   These  include  the  following; 

Appendix  Contents 

A  Summary  of  I/O  functions  by  device 

B  I/O  function  and  status  codes 

C  QIO$  interface  to  Ancillaiy  Control 

Processors 


ASSOCIATED  DOCUMENTS 

Other  ir.anuals  closely  allied  to  the   purposes  of   this  document  are 

described  briefly  in  the  RSX-llM/RSX-llS  Information  Directory  and  the 

RSX-llM-PLUS   information  Directory.    Each  DirectoTy  defines  the 

intended  ireadership  of  each  manual  in  the  RSX-llM/RSX -IIS  or 
i^SX-llM-PLu'S  set  and  provides  a  brief  synopsis  of  each  manual's 
contents. 


CONVENTIONS  USED  IN  THIS  MANUAL 

There  are  a  number  of  conventions  and  assumptions  used  in  this  manual 
to  present  sy.itax  and  program  coding  ex/imples.  These  are  described  in 
the  following  list. 

1.  Brai^kets   ([])    in   syntactic   models   enclose   optional 
p..:  o.ueters. 

The  following  example  illustrates  this  format: 

ASTX$S   [errl 

2.  Braces  (  |  }  )  in  syntactic  models  indicate   that  one  of   the 
items  must  be  selected,  as  in  the  following: 

iDOM  ) 
/<inm,icont,idata,[idx] , [isb] , [lun] > 


(domw) 


3.  An  ellipsis  (...)  in  a  syntactic  model  or  coding  example 
Indicates  that  parameters  have  been  omitted.  As  used  in  this 
manual,  an  ellipsis  in  a  QIO  macro  call  indicates  omission  of 
standard  QIO  parameters  described  in  Section  1.5.1.  This  is 
illustrated  below: 

QIO$C   lO.RLV, . . . ,<stadd,size> 

4.  Consecutive  commas  in  a  coding  example  indicate  null 
arguments.   The  following  Illustrates  this  usage: 

QIO$C   IO.ATT,6,,,,AST01 

5.  Commas  indicating  null  trailing  optional  arguments  may  be 
omitted,  as  in  the  following: 

QIOSC   I0.KIL,9. 
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6.  Certain  parameters  are  required  but  ignored  by  RSX-llM  or 
RSX-llM-PLUS;  this  is  necessary  to  maintain  compatibility 
with  RSX-llD.  For  example,  in  the  following,  the  priority 
specification  (fourth  parameter)  is  ignored: 

0IO$C   I0.WLB,8.,EV,,I0SB,ASTX,<I0BUF,NBUF> 

7.  With  the  exception  of  MACRO-11  coding  examples,  all  numbers 
in  the  text  of  this  manual  are  assumed  to  be  decimal;  octal 
radix  is  explicitly  declared  as  in  the  following: 

An  illegal  logical  block  number   has  been   specified 
for  DECtape.   The  number  exceeds  577  (1101  octal). 

In  MACRO-11  coding  examples,  all  numbers  are  assumed  to  be 
octal;  decimal  radix  is  explicitly  designated  by  tollowing 
the  number  with  a  decimal  point,  as  in  the  following  example: 

QIOSC   I0.RDB,14., ,,IOSB,,<IOBUF,80.> 

8.  In  FORTRAN  subroutine  models,  parameters  which  begin  with  the 
letters  I  through  n  indicate  integer  variables,  as  in  the 
following  example: 

CALL  DRS  (ibuf,ilen,imode, irate, iefn,imask,isb, 
[nbufl , [istart] , [istop] ) 

In  general,  where  both  i  and  n  prefixes  are  used  in  a  call, 
the  i  form  indicates  the  name  of  an  array  and  the  n  form 
specifies  the  size  of  the  array. 

All  integer  arrays  and  variables  are  assumed  to  occupy  one 
storage  word  per  variable  (that  is,  INTEGER*2)  and  all  real 
arrays  and  variables  are  assumed  to  occupy  two  storage  words 
per  variable  (that  is,  REAL*4). 
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SOmART  OP  TBCHHICAL  CHMIGBS 

This  update  to  the  I/O  Drivers  Reference  Manual  contains  changes  and 
additions  to  document  two  operating  systems:  RSX-llM  V4.1  and 
RSX-IIM-PLUS  V2.1.  The  following  list  contains  a  brief  summary  of 
technical  changes  for  both  operating  systems: 

•  Terminal  driver  support  has  been  added   for  the  following 
terminals: 

LQP02 

LA50 

DHVll 

•  Disk  driver  support  has  been  added  for  the  following  new  disk 
devices: 

UDAS<i>/RA81 

UDA50/RA60 

RC25 

RD51 

RX50 

•  Magnetic  tape  driver  support  has  been  added  for  the  TU80  and 
TSV05. 

•  Line  printer  driver  support  has  been  added  for  the  following 
printers: 

LNOl 
LP07 
LP26 
LP27 
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1.1   OVBRVIEN  OF  Rt>A-llH  I/O 

The  RSX-llM/M-PLUS  Real-Time  Executives  support  a  wide  variety  of 
PDP-11  input  and  output  devices,  including  disks,  DECtapes,  magnetic 
tapes,  tape  cassettes,  line  printers,  card  readers,  and  such 
laboratory  and  industrial  devices  as  analog-to-digital  converters, 
universal  digital  controllers,  and  laboratory  peripheral  systems. 
Drivers  for  '-hese  devices  are  supplied  by  Digital  Equipment 
Corporation  as  part  of  the  system  software.  This  manual  describes  all 
of  the  device  drivers  supported  by  the  system  and  the  characteristics, 
functions,  error  conditions,  and  programming  hints  associated  with 
each.  Devices  not  described  in  this  manual  can  be  added  to  basic 
system  configurations,  but  users  must  develop  and  maintain  their  own 
drivers  for  these  devices.  (See  the  RSX-llM  Guide  to  Writing  an  I/O 
Driver,  including  Update  No.  1,  or  the  RSX-llM-PLUS  Guide  to  Writing 
an  I/O  Driver ,  depending  upon  the  system  you  are  using.) 

Input/output  operations  under  RSX-llM  are  extremely  flexible  and  are 
as  device-  and  function-independent  as  possible.  Programs  issue  I/O 
requests  to  logical  units  that  have  been  previously  associated  with 
particular  physical  device  units.  Each  program  or  task  is  able  to 
establish  its  own  correspondence  between  physical  device  units  and 
logical  unit  numbers  (LUNs) .  I/O  requests  are  queued  as  issued;  they 
are  subsequently  processed  according  to  the  relative  priority  of  the 
tasks  that  issued  them.  I/O  requests  (for  appropriate  devices)  can  be 
issued  from  tasks  by  means  of  either  the  File  Control  Services  or 
Record  Management  Services,  or  can  be  interfaced  directly  to  an  I/O 
driver  by  means  of  the  Queue  I/O  (QIO)  system  directive. 

All  of  the  I/O  services  described  in  this  manual  are  requested  by  the 
user  in  the  form  of  QIO  system  directives.  A  function  code  included 
in  the  QIO  directive  indicates  the  particular  input  or  output 
operation  to  be  performed.  I/O  fuiictions  can  be  used  to  request  such 
operations  as: 

•  Attaching  or  detaching  a  physical  device   unit   for   a   task's 
exclusive  use 

•  Reading  or  writing  a  logical  or  virtual  block  of  data 

•  Cancelling  a  task's  I/O  requests 

A  wide  variety  of  device-specific  input/output  operations  (for 
example,  reading  DECtape  in  reverse,  rewinding  cassette  tape)  can  also 
be  specified  with  QIO  directives. 
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1.2   PHYSICAL,  LOGICAL,  AMD  VIRTUAL  I/O 

There  are  three  possible  modes  in  which  an  I/O  transfec  can  take 
place:   physical,  logical,  and  virtual. 

Physical  I/O  concerns  reading  and  writing  data  in  the  actual  physical 
units  accepted  by  the  hardware  (for  example,  sectors  on  a  disk).  For 
most  devices,  physical  I/O  is  identical  to  logical  I/O.  For  example, 
the  RK05  disk  has  sectors  of  256  words,  the  same  size  ai  RSX-llH 
logical  blocks  for  all  disks.  Thus,  in  this  case,  a  logical  block 
maps  directly  into  a  physical  block.  For  other  devices,  the  mapping 
is  not  one  to  one.  The  RFll  disk,  for  example,  is  word  addressable; 
however,  no  physical  I/O  may  be  done  with  the  RFll.  Data  is  always 
written  in  256-word  logical  blocks.  Another  example  is  the  RXOl 
flexible  disk.  Data  for  the  RXOl  is  recorded  in  physical  sectors  of 
64  word!)  each.  Therefore,  logical  blocks  for  the  RXOl  are  made  up  of 
four  physical  sectors. 

Logical  I/O  concerns  reading  and  writing  data  in  blocks  that  are 
convenient  for  the  operating  system.  In  most  cases,  logical  blocks 
map  directly  into  physical  blocks.  For  block-structured  devices  (for 
example,  disks)  ,  logical  blocks  are  numbered  beginning  at  0.  For 
non-block-structured  devices  (for  example,  terminals) ,  logical  blocks 
are  not  addressable. 

Virtual  I/O  concerns  reading  and  writing  data  to  open  files.  In  this 
case,  the  executive  maps  virtual  blocks  into  logical  blocks.  For 
file-structured  devices  (disks  or  DECtapes) ,  virtual  blocks  are  the 
same  size  as  logical  blocks  and  are  numbered  starting  from  one  (1)  and 
are  relative  to  the  file  rather  than  to  the  device.  For 
non-file-structured  devices,  the  mapping  from  virtual  block  to  logical 
block  is  direct. 


1.3   RSX-llN  DEVICES 

The  devices  listed  below  are  supported  by  both  RSX-llM  and 
RSX-llM-PLUS,  except  as  indicated.  Drivers  are  supplied  for  each  of 
these  devices,  and  I/O  operations  for  them  are  described  in  detail  in 
subsequent  chapters  of  this  manual. 

1.   A  variety  of  terminals,  including  the  following: 

•  ASP/KSR-33  and  ASR/KSR-35  Teletypes^ 

•  LA12  DECwriter 
e   LAIOO  DiSCwriter 

e   LA30  DECwriters  (serial  and  parallel) 

•  LA34/LA38  DECwriter  IV 

•  LA36  DECwriter  II 

e   LA120  DECwriter  III 
e   LA180S  DECprinter 

•  LQP02  Letter-Quality  Printer 


1.  Teletype  is  a  registered  trademark  of  the  Teletype  Corporation. 
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LA50  Personal  Printer 

VT05B  Alphanumeric  Display  Terminal 

VT50  Alphanumeric  Display  Terminal 

VT50H  Alphanumeric  Display  Terminal 

VT52  Alphanumeric  Display  Terminal 

VT55  Graphics  Display  Terminal 

VT61  Alphanumeric  Display  Terminal 

VTIOO  Alphanumeric  Display  Terminal 

VTlOl  Alphanumeric  Display  Terminal 

VT102  Alphanumeric  Display  Terminal 

VTIO   Alphanumeric  Display  Terminal 

VT125  Alphanumeric  Display  Terminal 

VT131  Alphanumeric  Display  Terminal 

VT132  Alphanumeric  Display  Terminal 

RT02  Data  Entry  Terminal 

RT02-C  Badge  Reader  and  Data  Entry  Terminal 

These  terminals  are  supported  on  the   following  asynchronous 
' ine  interfaces : 

DJll  Asynchronous  Co.timunication  Line  Interface  Multiplexer 

DHll   and   DH11~DM11-BB  Asynchronous  Communication   Line 
Interface  Multiplexer 


DHVll   Asynchronous   Communications 
Multiplexer 


DLll-A,   DLll-B,   DLll-C,   DLll-D,    DLll-E 
Asynchronous  Communication  Line  Interfaces 


Line    Interface 
and    DLll-W 


DLVll-E,    DLVll-F    Asynchronous 
Interfaces 


Communication 


Line 


DZll  Asynchronous  Communication  Line  Interface  Multiplexer 
variety  of  disks,  including  the  following: 
ML-11  Faet  Electronic  Mass  Storage  Device 
RFll/RSll  Bixed-Head  Disk 
RS03/RS04  Fixed-Head  Disk 
UDA50/RA80/RA81  Fixed-Media  Disk 
UDA50/RA60  Pack  Disk 
RM80  Fixed-Media  Disk 
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•  RP07  Fixed-Media  Disk 

•  RPI1/RP02  or  RP03  Pack  Disks 
e  RM02,  RM03,  RM05  Pack  Disk 

•  RP04,  RP05,  RP06  Pack  Disks 

e  RK11/RK05  or  RK05F  Cartridge  Disks 

•  RLIl/RLOl  or  RL02  Cartridge  Disk 

•  RK611/RK06  or  RK07  Cartridge  Disk 

•  RC25  Fixed-Media/Removable  Cartridge  Disk  Subsystem 

•  RD51  Fixed-Media  Disk 
e  RX50  Flexible  Disk 

•  RXll/RXOl  Flexible  Disk 

•  RX211/RX02  Flexible  Disk 

3.  TC11/TU56  DECtape 

4.  DL11/TU58  DECtape  II 

5.  A  variety  of  magnetic  tapes  including  the  following: 

•  TU80  Magnetic  Tape  Subsystem 

•  TSV05  Magnetic  Tape  Subsystem 

•  TSll  Magnetic  Tape  Subsystem 

•  TMll  Magnetic  Tape   Controller   with   TE10,TU10,   or   TS03 
Drive 

•  RHll/70  Controller  with  TM02/03  Formatter  and  TE16,   TU16, 
or  TU45  Drive 

•  RHll/70  Controller  with  TM03  Formatter  and  TU77  Drive 

•  RH11/RH70  Controller  with  TM78  Formatter  and  TU78  Drive 

6.  TAll  Tape  Cassette 

7.  A  variety  of  line  printers: 

LPll  Controller  with  LP14,  LPOl,  LP02,  LP04,   LP05,   LP06, 
LP07,  LP26,  LP27  Line  Printers 

LSll  Controller  and  Line  Printer 

LVll  Controller  with  LVOl  Line  Printer 

LA180  Controller  and  Line  Printer 

LNOl  Laser  Printer 

8.  CRll  Card  Reader 
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9.  Synchronous  and  asynchronous  line  interfaces: 

e  DAll-B  Asynchronous  Communication  Line  Interface   (RSX-llM 
support  only) 

e  DLll-E  Asynchronous  Communication  Line  Interface   (RSX-llM 
support  only) 

e  DLVll-E  Asynchronous  Communication  Line  Interface 

•  DNCll  Synchronous  Communication  Line  Interface 

e   DPll  Synchronous  Communication  Line   Interface   (RSX-llM 
support  only) 

e  DQll  Synchronous  Communication   Line   Interface   (RSX-llM 
support  only) 

e  DUll  Synchronous  Communication  Line  Interface   (RSX-llM 
support  only) 

e  DOPll  Synchronous  Communication  Line  Interface 
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10.  Two  analog-to-digltal  converters: 

•  APCll  Analog-to-Digital  Converter  (RSX-llM  support  only) 

•  ADOl-D  Analog-to-Digital  Converter  (RSX-llM  support  only) 

11.  UDCll  Universal  Digital  Controller  (RSX-llM  support  only) 

12.  Laboratory  peripheral  systems: 

•  ARll  Laboratory  Peripheral  System  (RSX-llM  support  only) 
e   LPSll  Laboratory  Peripheral  System  (RSX-llM  support  only) 

13.  Paper  tape  devices: 

•  PCll  Paper  Tape  Reader/Punch 

•  PRll  Paper  Tape  Reader 

14.  Industrial  control  subsystems: 

e   ICS/ICR  Local  and  Remote  Subsystems  (RSX-llM  support  only) 

e   DSS/DRS  Digital   Input   and   Output   Subsystems   (RSX-llM 
support  only) 

15.  The  "Null  Device,"   a   software  construct   that   facilitates 
eliminating  unwanted  output 

16.  Two  graphics  subsystems: 

•  VTll  Graphics  Display  System  (RSX-llM  support  only) 
e   VSfiO  Graphics  Display  System  (RSX-llM  support  only) 

17.  Laboratory  Peripheral  Accelerator: 
e   LPAll-K 

18.  K-series  laboratory  peripherals: 

e  AAll-K  Digital-to-Analog  Converter  and  Display 

e  ADll-K  Analog-to-DIgital  Converter 

•  AMll-K  Multiple-Gain  Multiplexer 

•  DRll-K  Digital  I/O  Interface 

•  KWll-K  Programmable  Real-Time  Clock 

19.  PCLll   Parallel   Communications   Link   (RSX-llM-PLUS   support 
only) 

20.  DT07  (RSX-llM-PLUS  support  only)  UNIBUS  Switch 

21.  Virtual  Terminals  (RSX-llM-PLUS  support  only) 

1.4   LOGICAL  UNITS 

This  section  describes  the  construction  of  the  logical  unit  table  and 
the  use  of  logical  unit  numbers. 
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1.4.1   Logical  Unit  Number 

A  logical  unit  number,  or  LUN,  is  a  number  associated  with  a  physical 
device  unit  during  RSX-1 IM/M-PLUS  I/O  operations.  For  example,  LUN  1 
might  be  associated  with  one  of  the  terminals  in  the  system,  LUNs  2, 
3,  4,  and  5  with  DECtape  drives,  and  LUNs  f,  7,  and  8  with  disk  units. 
The  association  is  a  dynamic  one;  each  task  running  in  the  system  can 
establish  its  own  correspondence  between  LUNs  and  physical  device 
units,  and  can  change  any  LUN/physical-device-unit  association  at 
almost  any  time.  The  flexibility  of  this  association  contributes 
heavily  to  system  device  independence. 

A  logical  unit  number  is  simply  a  short  name  used  to  represent  a 
loglcal-uni t/physical-device-unit  association.  Once  the  association 
has  been  made,  the  LUN  provides  a  direct  and  efficient  mapping  to  the 
physical  device  unit,  and  eliminates  the  necessity  to  search  the 
device  tables  whenever  the  system  encounters  a  reference  to  a  physical 
device  unit. 

The  user  should  remember  that,  although  a  LUN/physlcal-devlce-unit 
association  can  be  changed  at  any  time,  reassignment  of  a  LUN  at  run 
time  causes  pending  I/O  requests  for  the  previous  LUN  assignment  to  be 
cancelled.  It  is  the  user's  responsibility  to  verify  that  all 
outstanding  I/O  requests  for  a  LUN  have  been  serviced  before  that  LUN 
is  associated  with  another  physical  device  unit. 


1.4.2   Logical  Unit  Table 

There  is  one  Logical  Unit  Table  (LUT)  for  each  task  running  in  a 
system.  This  table  is  a  variable-length  block  contained  in  the  task 
header.  Each  LUT  contains  sufficient  2-word  entries  for  the  number  of 
logical  units  specified  by  the  user  at  task-build  time  by  the  "UNITS^" 
option. 

Each  entry  or  slot  contains  a  pointer  to  the  physical  device  unit 
currently  associated  with  that  LUN.  Whenever  a  user  Issues  an  I/O 
request,  the  system  matches  the  appropriate  physical  device  unit  to 
the  LUN  specified  in  the  call  by  indexing  into  the  LUT  by  the  number 
supplied  as  the  LUN.  Thus,  If  the  call  specifies  6  as  the  LUN,  the 
system  accesses  the  sixth  2-word  entry  in  the  LUT  and  associates  the 
I/O  request  with  the  physical  device  unit  to  which  the  entry  points. 
The  number  of  LUN  assignments  valid  for  a  task  ranges  from  0  to  255, 
but  cannot  be  greater  than  the  number  of  LUNs  specified  at  task-build 
time. 


Figure  1-1  illustrates  a  typical  Logical  Unit  Table. 


LUN  1 

0 

LUN  2 

0 

LUN  3 

0 

LUN  4 

0 

NUMsen  or  lums 

UCB 


UCB 


UCB 


Figure  1-1   Logical  Unit  Table 
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Word  1  of  each  active  (assigned)  2-word  entry  in  the  logical  unit 
table  points  to  the  Unit  Control  Block  (UCB)  of  the  physical  device 
unit  with  which  the  LUN  is  associated.  This  linkage  may  be  indirect; 
that  is,  the  user  may  force  redirection  of  references  from  one  unit  to 
another  unit  with  the  MCR  command  REDIRECT.  Word  2  of  each  entry  is 
reserved  for  mountable  devices. 


1.4.3  Changing  LUN  Assignments 

Logical  unit  numbers  have  no  significance  until  they  are  associated 
with  a  physical  device  unit  by  means  of  one  of  the  methods  described 
below: 

1.  At  task-build  time,  the  user  can  specify  an  ASG  keyword 
option,  which  associates  a  physical  device  unit  with  a 
logical  unit  number  referenced  in  the  task  being  built. 

2.  The  user  or  system  operator  can  issue  a  REASSIGN  command  to 
MCR;  this  command  reassigns  a  LUN  to  another  physical  device 
unit  and  thus  changes  the  LUN-physical  device  unit 
correspondence.  Note  that  this  reassignment  has  no  effect  on 
the  in-core  image  of  a  task. 

3.  At  run  time,  a  task  can  dynamically  change  a  LUN  assignment 
by  issuing  the  Assign  LUN  system  directive,  which  changes  the 
association  of  a  LUN  with  a  physical  device  unit  during  task 
execution. 


1.5   ISSUING  AN  I/O  REQUEST 

User  tasks  perform  I/O  i--!  the  RSX-llM/M-PLUS  system  by  submitting 
requests  for  I/O  service  in  the  form  of  QIO  or  QIO  And  Wait  system 
directives.  See  the  RSX-llM/M-PLUS  Executive  Reference  Manual  for  a 
complete  description  of  system  directives. 

In  RSX-1 IM/M-PLUS,  as  in  most  multiprogramming  systems,  tasks  do  not 
normally  access  physical  device  units  directly.  Instead,  they  utilize 
input/output  services  provided  by  the  Executive,  since  it  can 
effectively  multiplex  the  use  of  physical  device  units  over  many 
users.  The  Executive  routes  I/O  requests  to  the  appropriate  device 
driver  and  queues  them  according  to  the  priority  of  the  requesting 
task.  I/O  operations  proceed  concurrently  with  other  activities  in  an 
RSX-llM/M-PLUS  system. 

Before  a  request  is  queued,  it  must  pass  a  battery  of  acceptance  tests 
administered  by  the  Executive.  If  the  request  fails,  it  is  rejected; 
this  rejection  is  signalled  by  the  setting  of  the  C-bit  when  the 
statement  following  the  QIO  is  executed.  It  is  good  programming 
practice  to  check  for  directive  rejection  by  following  the  QIO 
directive  with  a  BCS  ' nstruction. 

After  an  I/O  request  has  been  queued,  the  system  does  not  wait  for  the 
operation  to  complete.  If  at  any  time  the  user  task  that  issued  the 
QIO  request  cannot  proceed  until  the  I/O  operation  has  completed,  it 
should  specify  an  event  flag  (see  Sections  1.5.1  and  1.5.2)  in  the  QIO 
request  and  should  issue  a  Waitfor  system  directive  specifying  the 
same  event  flag  at  the  point  where  synchronization  must  occur.  The 
task  then  waits  for  completion  of  I/O  by  waiting  for  the  specified 
event  flag  to  be  set. 
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The  OIOW  directive,  QIO  And  Wait,  is  a  more  economical  way  to  achieve 
this  synchronization.  QIOW  automatically  waits  until  I/O  has 
completed  before  returning  control  to  the  task.  Thus,  the  additional 
Waitfor  directive  is  not  necessary. 

Bach  QIO  or  QIOW  directive  must  supply  sufficient  information  to 
identify  and  queue  the  I/O  request.  The  user  may  also  want  to  include 
locations  to  receive  error  or  status  codes  and  to  specify  the  address 
of  an  asynchronous  system  trap  service  routine.  Certain  types  of  I/O 
operations  require  the  specification  of  device-dependent  information 
as  well.   Typical  QIO  parameters  are  the  following: 

•  I/O  function  to  be  performed 

•  Logical  unit  number  associated  with  the  physical  device  unit 
to  be  accessed 

•  Optional  event  flag  number  for  synchronizing  I/O  completion 
processing  (required  for  QIOW) 

•  Optional  address  of  the  I/O  status  block  to  wtiich  information 
indicating  successful  or  unsuccessful  completion  is  returned 

•  Optional  address  of  an  asynchronous  system  trap  service 
routine  to  be  entered  on  completion  of  the  I/O  request 

•  Optional  device-  and  function-dependent  parameters  specifying 
such  items  as  the  starting  address  of  a  data  buffer,  the  size 
of  the  buffer,  and  a  block  number 

A  set  of  system  macros  that  facilitate  the  issuing  of  QIO  directives 
is  supplied  with  the  RSX-llM/M-PLUS  system.  These  macros,  which 
reside  in  the  System  Macro  Library  (LB: [ 1 , 1] RSXMAC. SML) ,  must  be  made 
available  to  the  source  program  by  means  of  the  MACRO-11  Assembler 
directive  .MCALL.  The  function  of  .MCALL  is  described  in  Section 
1.7.3.  Several  of  the  first  six  parameters  in  the  QIO  directive  are 
optional,  but  space  for  these  parameters  must  be  reserved. 

During  expansion  of  a  QIO  macro,  a  value  of  0  is  defaulted  for  all 
null  (omitted)  parameters.  Inclusion  of  the  device-  and 
function-dependent  parameters  depends  on  the  physical  device  unit  and 
function  specified.  If  the  user  wanted  to  specify  only  an  I/O 
function  code,  a  LUN,  and  an  address  for  an  asynchronous  system  trap 
service  routine,  the  following  might  be  issued: 

QIOSC    I0.ATT,6, ,, ,ASTOX 

10. ATT 

The  I/O  function  code  for  attach. 


The  LUN. 

ASTOX 

The  AST  address, 
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Null  arguments  for  the  event  flag  number,  the   request   priority, 
and  the  address  of  the  I/O  status  block. 

No  additional  device-  or  function-dependent  parameters  are  required 
for  an  attach  function.  The  C  form  of  the  QIO$  macro  is  used  here  and 
in  most  of  the  examples  included  in  Chapter  1.  Section  1.1  describes 
the  three  legal  forms  of  the  macro. 

For  convenience,  any  comma  may  be  omitted  if  no  parameters  appear  to 
the  right  of  it.  The  command  above  could  tnerefore  be  issued  as 
follows,  if  the  asynchronous  system  trap  was  not  desired: 

0IO$C   10. ATT, 6 

All  extra  commas  have  been  dropped.  If,  however,  a  parameter  appears 
to  the  right  of  any  place-holding  comma,  that  comma  must  be  retained. 


1.5.1   QIO  Macro  Format 

The  arguments  for  a  specific  QIO  macro  call  may  be  different  for  each 
I/O  device  accessed  and  for  each  I/O  function  requested.  The  general 
format  of  the  call  is,  however,  common  to  all  devices  and  is  as 
follows : 

QIO$C   fnc,lun, [efn] , fpri] , [isb] , tast] [ ,<pl,p2, . . . ,p6>] 

where  brackets  {[])  enclose  optional  or  function-dependent  parameters. 
If  function-dependent  parameters  <pl,...,p6>  are  required,  these 
parameters  must  be  enclosed  within  angle  brackets  (<>).  The  following 
paragraphs  summarize  the  use  of  each  QIO  parameter.  Section  1.7 
discusses  different  forms  of  the  QIO$  macro  itself. 

The  fnc  parameter  is  a  symbolic  name  representing  the  I/O  function  to 
be  performed.   This  name  is  of  the  form 

10. XXX 


XXX 

Identifies  the  particular  I/O  operation. 

For  example,  a  QIO  request  to  attach  the  physical  device  unit 
associav.ed  with  a  LUN  specifies  the  function  code 

10. ATT 

A  QIO  request  to  cancel  (or  kill)  all  I/O  requests  for  a  specified  LUN 
begins  in  the  following  way: 

QIO$C   lO.KIL,... 

The  fnc  parameter  specified  in  the  QIO  request  is  stored  internally  as 
a  function  code  in  the  high-order  byte  and  modifier  bits  in  the 
low-order  byte  of  a  single  word.  The  function  code  is  in  the  range  0 
through  31  and  is  a  binary  value  supplied  by  the  system  to  match  the 
symbolic  name  specified  in  the  QIO  request.  The  correspondence 
between  global   symbolic  names  and   function  codes   is  defined   in  the 
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system  object  module  library,  which  is  automatically  searched  by  the 
Task  Builder.  Local  symbolic  definitions  may  also  be  obtained  by  the 
FILIOS  and  SPCIOS  macros,  which  reside  in  the  System  Macro  Library  and 
are  summarized  in  Appendix  A.  Several  similar  functions  may  have 
If'sntical  function  codes,  and  may  be  distinguished  only  by  their 
mccifier  bits.  For  example,  the  DECtape  read  logical  forward  and  read 
logical  reverse  functions  have  the  same  function  code.  Only  the 
modifier  bits  for  these  two  operations  are  stored  differently. 

The  lun  parameter  represents  the  logical  unit  number  (LUN)  of  the 
associated  physical  device  unit  to  be  accessed  by  the  I/O  request. 
The  association  between  the  physical  device  unit  and  the  LUN  is 
specific  to  the  task  that  issues  the  1/0  request,  and  the  LUN 
reference  is  usually  device  independent.  An  attach  request  to  the 
physical  device  unit  associated  with  LUN  14  begins  in  the  following 
way: 


device 
a  LUN 
in   a 


OIOSC   lO.ATT, 14. ,. .. 

Because  each  task  has   its   own   LUT   in   which   the   physical 
unit-LUN   correspondences   are   established,   the   legality   of 
parameter  is  specific  to  the  task  that  includes  this   parameter 
QIC  request.   In  general,  the  LUN  must  be  in  the  following  range: 

0   <LUN   <length  of  task's  LUT  (if  nonzero) 

The  number  of  LUNs  specified  in  the  LUT  of  a   particular   task   cannot 
exceed  255. 


The  efn  parameter  is  a   number   representing   the   event   flag   to   be 
associated  with  the  I/O  operation.   It  may  optionally  be  included  in  a 


010  or  OIO  And  Wait  request, 
the   I/O   request   is   queued 
completed.   If  the   task   has 
execution   i?   automatically 
OIO  directive  has  been  issued 


The  specified  event  flag  is  cleared  when 
and  is  set  when  the  I/O  operation  has 
issued  the  QIO  And  Wait  directive, 
suspended  until  the  I/O  completes.  If  a 
(with  no  Waitfor  directive),  then  task 
execution  proceeds  in  parallel  with  the  I/O.  When  the  task  continues 
to  execute,  it  may  test  the  event  flag  whenever  it  chooses  by  using 
the  Read  All  Event  Flags  system  directive  (if  group  global  event  flags 
are  not  being  used)  or  the  Read  Extended  Flags  system  directive  (for 
all  event  flags,  including  group-global  event  flags).  If  the  user 
specifies  an  event  flag  number,  this  number  must  be  in  the  range  1 
through  96.  If  an  event  flag  specification  is  not  desired,  efn  can  be 
omitted  or  can  be  supplied  with  a  value  of  0.  Event  flags  1  through 
32  are  local  (specific  to  the  issuing  task);  event  flags  31  through 
fi4  are  global  (shared  by  all  tasks  in  the  system).  Event  flags  65 
through  96  are  group-global  event  flags  (shared  by  all  tasks  in  the 
same  user  group) .  Flags  25  through  32  and  57  through  64  are  reserved 
for  use  by  system  software.  Within  these  bounds,  the  user  can  specify 
event  flags  as  desired  to  synchronize  I/O  completion  and  task 
execution.  Section  1.5.2  provides  a  more  detailed  explanat  on  of 
event  flags  and  significant  events. 


NOTE 

If  an  event  flag  is  not  specified,  the 
Executive  treats  the  directive  as  if  it 
were  a  simple  QIO  request. 


m 
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The  optional  pri  parameter  is  sjpplied  only  to  make  RSX-1 IM/M-PLUS  010 
requests  compatible  with  RSX-llD.  An  RSX-llM  I/O  request 
automatically  assumes  the  priority  of  tha  requesting  task.  Thus,  it 
is  recommended  that  a  value  of  0  (or  a  null)  be  used  for  this 
parameter . 
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The  correspondence  between  global  symbolic  names  and  I/O  completion 
codes  is  defined  in  the  system  object  module  library,  which  is 
automatically  searched  by  TKB.  Local  symbolic  definitions,  which  are 
summarized  in  Appendix  B,  may  also  be  obtained  by  the  lOERRS  macro, 
which  resides  in  the  System  Macro  Library. 

Certain  device-dependent  information  is  returned  to  the  high-order 
tjyte  of  the  first  word  of  isb  on  completion  of  the  I/O  operation.  If 
a  read  or  write  operation  is  successful,  the  second  word  is  also 
significant.  For  example,  in  the  case  of  a  read  function  on  a 
terminal,  the  number  of  bytes  typed  before  a  carriage  return  is 
returned  in  the  second  word  of  isb.  If  a  magtape  unit  is  the  device 
and  a  write  function  is  specified,  this  number  represents  the  number 
of  bytes  actually  transferred.  The  status  block  can  be  omitted  from  a 
QIO  request  if  the  user  does  not  intend  to  test  for  successful 
completion  of  the  request. 
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1.5.2  Significant  Events 

"Significant  event"  is  a  term  used  in  real-time  systems  to  indicate  a 
change  in  system  status.  In  RSX-llM/M-PLUS,  a  significant  event  is 
declared  when  an  I/O  operation  completes.  This  signals  the  system 
that  a  change  in  status  has  occurred  and  indicates  that  the  Executive 
should  review  the  eligibility  of  all  tasks  in  the  system  to  determine 
which  task  should  run  next.  The  use  of  significant  events  helps 
cooperating  tasks  in  a  real-time  system  to  communicate  with  each 
other,  and  thus  allows  these  tasks  to  control  their  own  sequence  of 
execution  dynamically. 

Significant  events  are  normally  set  by  system  directives,  either 
directly  or  indirectly,  by  completion  of  a  specified  function.  Event 
flags  associated  with  tasks  may  be  used  to  indicate  which  significant 
event  has  occurred.  Of  the  9fi  event  flags  available  in 
RSX-llM/M-PLUS,  the  flags  numbered  1  through  32  are  local  to  an 
individual  task  and  are  set  or  reset  only  as  a  result  of  that  task's 
operation.  The  event  flags  numbered  33  through  64  are  common  to  all 
tasks.  Flags  25  through  32  and  57  through  64  are  reserved  for  system 
software  use.  The  event  flags  numbered  65  through  96  are  group-global 
event  flags,  which  are  common  to  all  tasks  running  under  the  same  user 
group. 

An  example  of  the  use  of  significant  events  follows.  A  task  issues  a 
QIO  directive  with  an  efn  parameter  specified.  A  Waitfor  directive 
follows  the  QIO  and  specifies  as  an  argument  the  same  event  flag 
number.  The  event  flag  is  cleared  when  the  I/O  request  "  queued  by 
the  Executive,  and  the  task  is  blocked  vhen  it  executes  the  Waitfor 
directive  until  the  event  flag  is  set  and  a  significant  event  is 
declared  at  the  completion  of  the  I/O  request.  The  task  resumes  when 
the  appropriate  event  flag  is  set,  and  execution  resumes  at  the 
instruction  following  the  Waitfor  directive.  During  the  time  that  the 
task  is  blocked,  other  tasks  have  a  chance  to  run,  thus  increasing 
throughput  in  the  system. 


1.5.3  System  Traps 

System  traps  are  used  to  interrupt  task  execution  and  to  cause  a 
transfer  of  control  to  another  memory  location  for  special  processing. 
Traps  are  handled  by  the  Executive  and  are  relevant  only  to  the  task 
in  which  they  occur.  To  use  a  system  trap,  a  task  must  contain  a  trap 
service  routine,  which  is  automatically  entered  when  the  trap  occurs. 

There  are  two  types  of  system  traps:  synchronous  and  asynchronous. 
Both  are  used  to  handle  error  or  event  conditions,  but  the  two  traps 
differ  in  their  relation  to  ^he  task  that  is  running  when  they  are 
detected.  Synchronous  traps  signal  error  conditions  within  the 
executing  task.  If  the  same  instruction  sequence  were  repeated,  the 
same  synchronous  trap  would  occur  at  the  same  place  in  the  task. 
Asynchronous  traps  signal  the  completion  of  an  external  event  such  as 
an  I/O  operation.  An  asynchronous  system  trap  (AST)  usually  occurs  as 
the  result  of  initiating  or  completing  an  external  event  rather  than  a 
program  condition. 

The  Executive  queues  ASTs  in  a  first-in-first-out  queue  for  each  task 
and  monitors  all  asynchronous  service  routine  operations.  Because 
asynchronous  traps  may  be  the  end  result  of  I/0-related  activity,  they 
cannot  be  controlled  directly  by  the  task  that  receives  them. 
However,  the  task  may,  under  certain  circumstances,  block  recognition 
of  ASTs  to   prevent   simultaneous  access   to  a   critical   data  region. 
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When  access  to  the  critical  data  region  has  been  completed,  the  queued 
ASTs  may  again  be  honored.  The  DSARSS  (Disable  AST  Recognition)  and 
ENAR$S  (Enable  AST  Recognition)  system  directives  provide  the 
mechanism  for  accomplishing  this.  An  example  of  an  asynchronous  trap 
condition  is  the  completion  of  an  I/O  request.  The  timing  of  such  an 
operation  clearly  cannot  be  predicted  by  the  requesting  task.  If  an 
AST  service  routine  is  not  specified  in  an  I/O  request,  a  trap  does 
not  occur  and  normal  task  execution  continues. 


Asynchronous  system  traps  associated  with  I/O  requests  enable  the 
requesting  task  to  be  truly  event  driven.  The  AST  service  routine 
contained  in  the  initiating  task  is  executed  as  soon  as  possible, 
consistent  with  the  task's  priority.  Using  the  AST  routine  to  service 
I/O-related  events  provides  a  response  time  that  is  considerably 
better  than  a  polling  mechanism,  and  provides  for  better  overlap 
processing  than  the  simple  QIO  and  Waitfor  sequence.  Asynchronous 
system  traps  also  provide  an  ideal  mechanism  for  use  in  multiple 
buffering  of  I/O  operations. 
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1.6   DIRECTIVE  PARAMETER  BLOCKS 


A  Directive  Parameter  Block  (DPB)  is  a  fixed-length  area  o 
memory  that  contains  the  arguments  specified  in  a  syst 
macro  call.  The  DPB  for  a  QIO  directive  has  a  length  of  1 
is  generated  as  the  result  of  expanding  a  QIO  macro  call 
byte  of  the  DPB  contains  the  directive  identification 
—  always  1  for  QIO.  The  second  byte  contains  the  size  o 
words  —  always  12  for  RSX-llM/M-PLUS.  During  assembly  of 
containing  QIO  requests,  the  MACRO-11  Assembler  generat 
each  I/O  request  specified  in  a  QIO  macro  call.  At  run 
Executive  uses  the  arguments  stored  in  each  DPB  to  crea 
request,  an  I/O  packet  in  system  dynamic  storage.  The 
entered  by  priority  into  a  queue  of  I/O  requests  for  t 
physical  device  unit.  This  queue  is  created  and  maintai 
Executive  and  is  ordered  by  the  priority  of  the  tasks  tha 
requests.  The  I/O  drivers  examine  their  respective  queues 
request  with  the  highest  priority  capable  of  being  exe 
request  is  dequeued  (removed  from  the  queue)  and  the  I/O  o 
performed.  The  process  is  then  repeated  until  the  queue  i 
all  requests. 
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After  the  I/O  request  has  been  completed,  the  Executive  declares  a 
significant  event  and  may  set  an  event  flag,  cause  a  branch  to  an 
asynchronous  system  trap  service  routine,  and/or  return  the  I/O 
status,  depending  on  the  arguments  specified  in  the  original  QIO  macro 
call.   Figure  1-2  illustrates  the  layout  of  a  sample  DPB. 


WORD  0  SIZE  OF  DPB 

2 

3  PRIORITY 

4 

8 


11 


1 

0 

12 

1 

FNC 

MODIFIERS 

Z  RESERVED  /y 

LUN 

PRI 

EFN 

ISB 

AST 

DEVICE- 
DEPENDENT 
PARAMETERS 

BYTE 

Die  FOR  QIO 
DIRECTIVE 

I/O  FUNCTION 
LOGICAL  UNIT  NUMBER 

EVENT  FLAG  NUMBER 

ADDRESS  OF  I/O 
STATUS  BLOCK 

ADDRESS  OF 
ASYNCHRONOUS  TRAP 
SERVICE  ROUTINE 


ZK-oos-ai 


Figure  1-2   QIO  Directive  Parameter  Block 


1.7   I/0-RELATED  MACROS 

Several  system  macros  are  supplied  with  the  RSX-llM/M-PLUS  system  to 
issue  and  return  information  about  I/O  requests.  These  macros  reside 
in  the  System  Macro  Library  and  must  be  made  available  during  assembly 
by  the  MACRO-11  assembler  directive  .MCALL. 

Also  supplied  are  FORTRAN-call able  subroutines  that  perform  the  same 
functions  as  the  system  macros.  See  the  RSX-llM/M-PLUS  Executive 
Reference  Manual  for  details. 

There  are  three  distinct  forms  of  most  of  the  system  directive  macros 
discussed  in  this  section.  The  following  list  summarizes  the  forms  of 
010$,  but  the  characteristics  of  each  form  also  apply  to  0IOW$,  ALUN$, 
GLUN$,  and  other  system  directive  macros  described  below. 

1.  010$  generates  a  directive  parameter  block  for  the  I/O 
request  at  assembly  time,  but  does  not  provide  the 
instructions  necessary  to  execute  the  request.  This  form  of 
the  request  is  actually  executed  using  the  DIR$  macro.  It  is 
useful  if  the  DPB  is  to  be  used  in  several  different  places 
in  the  task  and/or  modified  or  referenced  by  the  task  at  run 
time. 
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2.  QIOSS  generates  a  directive  parameter  block  for  the  I/O 
request  on  the  stack,  and  also  generates  code  to  execute  the 
request.  This  is  a  useful  form  for  reentrant,  shareable  code 
since  the  DPB  is  generated  dynamically  at  execution  time. 

3.  OIOSC  generates  a  directive  parameter  block  for  the  I/O 
request  at  assembly  time,  and  also  generates  code  to  execute 
the  request.  The  DPB  is  generated  in  a  separate  program 
section  called  $DPB$$.  This  approach  incurs  little  system 
overhead  and  is  useful  when  an  I/O  request  is  executed  from 
only  one  place  in  the  program. 

Parameters  for  both  the  QIOS  and  OIOSC  forms  of  the  macro  must  be 
valid  expressions  to  be  used  in  assembler  data-generating  directives 
such  as  .WORD  and  .BYTE.  Parameters  for  the  QIOSS  form  must  be  valid 
source  operand  address  expressions  to  be  used  in  assembler 
instructions  such  as  MOV  and  MOVB.  The  following  example  references 
the  same  parameters  in  the  three  distinct  forms  of  the  macro  call. 

OIOS      I0.RLB,fi,2, ,,AST01,<RDBUF,80.> 

OIOSC     I0.RLB,fi,2, ,,AST01,<RDBUF,80.> 

OIOSS     iIO.RLB,l6,i2,,,#AST01,<#RDBUF,#80.> 

Only  the  QIOSS  form  of  the  macro  produces  the  DPB  dynamically.  I'he 
other  two  forms  generate  the  DPB  at  assembly  time.  The 
characteristics  and  use  of  these  different  forms  are  described  in 
greater  detail  in  the  RSX-llM/M-PLUS  Executive  Reference  Manual . 

The  following  Executive  directives  and  assembler  macros  are  described 
in  this  section: 

1.  OIOS,  which  is  used  to  request  an  I/O  operation  and  supply 
parameters  for  that  request 

2.  OIOWS,  which  is  equivalent  to  QIOS  followed  by  WTSES 

3.  DIRS,  which  specifies  the  address  of  a  directive  parameter 
block  as  its  argument,  and  generates  code  to  execute  the 
directive 

4.  .MCALL,  which  is  used  to  make  avail<>tble  from  the  System  Macro 
Library  all  macros  referenced  during  task  assembly 

5.  ALUNS,  which  is  used  to  associate  a  logical  unit  number  with 
a  physical  device  unit  at  run  time 

^.  GLUNS,  which  requests  that  the  information  about  a  physical 
device  unit  associated  with  a  specified  LUN  be  returned  to  a 
user-specified  buffer 

7.  ASTXSS,  which  is  used  to  terminate  execution  of  an 
asynchronous  system  trap  (AST)  service  routine 

8.  WTSES,  which  instructs  the  system  to  block  execution  of  the 
issuing  task  until  a  specified  event  flag  is  set 
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1.7.1  The  010$  Macro:  Issuing  an  I/O  Request 

As  described  in  Section  1.7,  there  are  three  distinct  forms  of  the 
0X0$  macro.  0IO$S  generates  a  DPB  for  the  I/O  request  on  the  stack, 
and  also  generates  code  to  execute  Lne  request.  0IO$C  generates  a  DPB 
and  code,  but  the  DPB  Is  generated  in  a  separate  program  section. 
010$  generates  only  the  DPB  for  the  I/O  request.  This  form  of  the 
macro  call  is  used  in  conjunction  with  DIRS  (see  Section  1.7.2)  to 
execute  an  I/O  request.  In  the  following  example,  the  DIR$  macro 
actually  generates  the  code  to  execute  the  QIO$  directive.  It 
provides  no  QIO  parameters!  of  its  own,  but  references  the  010 
directive  parameter  block  at  address  QIOREF  by  supplying  this  label  as 
an  argument. 


QIOREF:   QIOS 


IO.RLB,6,2, ,,AST01,<BUFFER,80.> 

;   CREATE  QIO  DPB 


READl:    DIRS     iQIOREF 


ISSUE  I/O  REQUEST 


READ2! 


DIRS 


#QIOREF 


ISSUE  I/O  REQUEST 


1.7.2  The  QIOW$  Macro:  Issuing  an  I/O  Request  and  Waiting  for  an 


Event 


'.ag 


The  QIOWS  macro  is  equivalent  to  a  QIOS  followed  by  a  WTSES.  It  is 
more  economical  to  issue  a  QIO  And  Wait  request  than  to  use  the  tvj 
separate  macros.  An  event  flag  (efn  parameter)  must  be  specified  with 
QIOWS. 


1.7.3   The  DIRS  Macro:  Executing  a  Directive 

The  DIRS  (execute  directive)  macro  has  boen   implemented   to   allow  a 
task  to  reference  a  previously  defined  DPB.   It  is  issued  in  the  form: 

DIRS    [addr]  [,err] 


addr 


The  address  of  a  directive  parameter  block  to  be  used  in  the 
directive.  If  addr  is  not  included,  the  DPB  itself  or  the 
address  of  the  DPB  is  assumed  to  already  be  on  the  stack.  This 
parameter  must  be  a  valid  source  operand  for  a  MOV  instruction 
generated  by  the  DIRS  macro. 


err 


An  optional  argunent  which  specifies  the  address  of  an  error 
routine  to  which  control  branches  if  the  directive  is  rejected. 
The  branch  occurs  by  means  of  a  JSR  PC,  err  if  the  C-bit  is  set, 
indicating  rejection  of  the  QIO  directive. 
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1.7.4  Th«  .MCALL  Directiv*:  Retrieving  System  Macros 

.MCALL  Is  a  MACRO-11  Assembler  directive  that  retrieves  macros  from 
the  System  Macro  Library  (L3: f 1 , I ] RSXMAC.SML)  for  use  during  assembly. 
It  must  be  included  in  every  user  task  invoking  system  macros.  .mcalL 
is  usually  placed  at  the  beginning  of  a  user-task  source  module  and 
specifies,  as  arguments  in  the  call,  all  system  macros  that  must  be 
made  available  from  the  library. 

The  following  example  illustrates  the  use  of  this  directive: 


.MCALL   010$, QIOSS, DIRS, WTSE$S 


ATTACH:  QIOSS    #10. ATT, f « , , , lOSB, •AST02 


OIOREF:  010$ 


READl:   DIR$ 


lO.RLB.fi, ,,IOSB,AST01, 


•OIOREF, DIRERR 


;  MAKE  MACROS  AVAILABLE 


ATTACH  DEVICE 


;  CREATE  ONLY  QIO  DPB 


ISSUE  I/O  REQUEST 


As  many  .-nacro  references  as  can  fit  on  a  line  can  be  included  in  a 
single  .MCALL  directive.  There  is  no  limit  to  the  number  of  .MCALL 
directives  that  can  be  specified. 


1.7.5  The  ALUNS  Macro:  Assigning  a  LUN 

The  Assign  LUN  macro  is  used  to  associate  a  logical  unit  number  with  a 
physical  device  unit  at  run  time.  All  three  forms  of  the  macro  call 
may  be  used.  Assign  LUN  does  not  request  I/O  for  the  physical  device 
unit,  nor  does  it  attach  the  unit  for  exclusive  use  by  the  issuing 
task.  It  simply  establishes  a  LUN-physical  device  unit  relationship, 
so  that  when  the  task  requests  I/O  for  that  particular  LUN,  the 
associated  ph/sical  device  unit  is  referenced.  The  macro  is  issued 
from  a  MACRO-ll  program  in  the  following  way: 


ALUNS    lun,dev,unt 


lun 


The  logical  unit  number 
physical  device  unit. 


to  be  associated  with  the  specified 


dev 


The  device  name  of  the  physical  device  or  a  logical 
assigned  to  a  physical  device  (see  MCR  ASN  command) 


device  namc' 


unt 


The  unit  number  of  that  aevlce  specified  above. 
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For  example,  to  associate  LUN  10  with  terminal  unit  2,  the  following 
macro  call  could  be  issued  by  the  task: 

ALUNSC   10. ,TT,2 

A  unit  number  of  0  represents  unit  0  for  multiunit  devices  such  as 
disk,  DECtape,  or  terminals;  it  indicates  the  single  available  unit 
for  devic'is  without  multiple  units,  such  as  card  readers  and  line 
printers. 

Logical  devices  are  SYSGEN  options  that  allow  the  user  to  assign 
logical  names  to  physical  devices  by  means  of  the  MCR  command  ASN. 
See  the  RSX-llM/M-PLUS  MCR  Operations  Manual  for  a  full  description. 

The  example  included  below  illustrates  the  use  of  the  three  forms  of 
the  ALUNS  macro. 


t    DATA  DEFINTTIONS 

; 

ASSIGN:  ALUN$    10.,TT,2 


GENERATE  DPB 


;  EXECUTABLE  SECTION 
I 

DIRS     #ASSIGN 


;  EXECUTE  DIRECTIVE 


ALUN$C   10.,TT,2 


GENERATE  DPB  IN  SEPARATE  PROGRAM 
SECTION,  THEN  GENERATE  CODE  TO 
EXECUTE  THE  DIRECTIVE 


ALUNSS   #10.,f"TI,#0   ;  GENERATE  DPB  ON  STACK,  THEN 

;  EXECUTE  DIRECTl  E 


1.7.5.1  Physical  Device  Names  -  The  following  list  contains  physical 
device  names,  listed  alphabetically,  that  may  be  included  as  dev 
parameters: 


Name 


Device 


m 

Ml 


ADOl-D  Analog-to-Digital  Converter  (not   supported   in 
RSX-llM-PLUS  systems) 

AFCll  Analog-to-Digital  Converter   (not   supported   in 
RSX-llM-PLUS  systems) 

ARll  Laboratory  Peripheral  System   (not   supported   in 
RSX-llM-PLUS  systems) 
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■•OM  D«vic« 

BS  DT03/DT07  UNIBUS  Switch  (supported  in  RSX-llM-PLUS 
systems  only) 

CD        CD 11  C«rd  Reader 

CP  Central  Processor  Unit  (CPU)  in  a  multiprocessor 
system  (supported  in  RSX-llM-PLUS  systems  only) 

CR  CRll/CMll  Card  Reader 

CT  TA11/TU60  Tape  Cassette 

DB  RP04,  RP05,  RP06  Pack  Disk 

DD  TU58  DECtape  II 

DP  RFll/RSll  Fixed-Head  Disk 

DK  RK11/RK05  Cartridge  Disk 

DL  RL11/RL01/RL02  Cartridge  Disk 

DM  RK611/RK06  and  RK711/RK07  Cartridge  Disk 

DP  RP11/RP02/RP03  Pack  Disk 

DR  RM02/RM03/RM05  Pack  Disk  and  RM80/RP07  Fixed-Media 
Disk 

DS        RS03  and  RS04  Fixed-Head  Disks 

DT        TC11/TU56  DECtape 

DU  RA80/RA81  Fixed-Media  Disk,  RA60  Pack  Disk,  RC25  Disk 
Subsystem,  RD51  Fixed-Media  Disk,  and  RX50  Flexible 
Disk 

DX        RXll/RXOl  Flexible  Disk 

DY        RX211/RX02  Flexible  Disk 

EM        ML-11  Fast  Electronic  Mass  Storage  Device 

GR  VT11/VS60  Graphics  Systems  (not  supported  in 
RSX-llM-PLUS  systems) 

IC  ICS/ICR  Industrial  Control  Local  and  Remote  Subsystems 
(not  supported  in  RSX-llM-PLUS  systems) 

IS  DSS/DRS  Digital  Input  and  Output  Subsystems  (not 
supported  in  RSX-llM-PLUS  systems) 

LA       LPAll-K  Laboratory  Peripheral  Accelerator 

LP  LA180/LP11/LS11/LV11  Line  Printers  and  LNOl  Laser 
Printer 

LS  LPSll  Laboratory  Peripheral  System  (not  supported  in 
RSX-llN-PLUS  systems) 
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Name  D«vic« 

mr  TU78  Magnetic  Tap* 

NH  TU16/TE16/TU45/TO77/TM02/TM03  Magnetic  Tape 

MS  TSll,  TU80,  or  TSV05  Magnetic  Tape 

Ht  TMll/TUlO/TOll  or  TS03  Magnetic  Tape 

Mb"  The  Null  Device 

§9  PCll  Paper  Tape  Punch 

ift  PCll  or  PRll  Paper  Tape  Reader 

Ut        PCLll-A/PCLll-B    R'^ceiver    Port     (supported     in 
RSX-llM-PLOS  systems  only) 

Tf        Terminals  (regardless  of  interface) 

tT        PCLll-A/PCLll-B    Transmitter    Port    (supported    in 
RSX-llM-PLUS  systems  only) 

OD        UDCll  Universal  Digital  Controller  (not   supported   in 
RSX-llM-PLUS  systems) 

XB        DAll-B   Parallel   Unibus   Linic    (not   supported    in 
RSX-llM-PLUS  systems) 

XL        DLll-E  Asynchronous  Communication  Line  Interface   (not 
supported  in  RSX-llM-PLUS  systems) 

XM        DMCll  Synchronous  Communication  Line  Interface 

XP        DPll  Synchronous   Communication   Line   Interface   (not 
supported  in  RSX-llM-PLUS  systems) 

XQ        DQll  Synchronous   Communication   Line   Interface   (not 
supported  in  RSX-llM-PLUS  systems) 

XU        DUll  Synchronous   Communication   Line   Interface   (not 
supported  in  RSX-llM-PLUS  systems) 

XW        DUPll  Synchronous  Communication  Line  Interface 

YH        DHll   or   DHVll   Asynchronous   Communications   Line 
Multiplexer 

YL        DLll-A/DLll-B/DLll-C/DLll-D/DLll-E  Asynchronous 

Communications   Line   Interface  (DLll-B,  DLll-E,  DPll, 

DQll,  and   DUll   are  not   supported   in  RSX-llM-PLUS 
systems) 

YZ        DZll  Asynchronous  Communications  Line  Multiplexer 

ZA-ZZ     Reserved  for  customer  use  (not  used  by  DIGITAL) 
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1.7.5.2  Ps«udo-D«vice  Naa«s  -  A  pseudo-device  is  a  logical  device 
that  can  normally  be  redirected  by  the  operator  to  another  physical 
device  unit  at  any  time,  without  requiring  changes  in  programs  that 
reference  the  pseudo-device.  Dynamic  redirection  of  a  physical  device 
unit  affects  all  tasks  in  the  system;  reassignment  by  means  of  the 
MCR  REASSIGN  command  affects  only  one  task.  The  following 
pseudo-devices  are  supported,  as  indicated: 

Cod*  Device 

<Q^  Console  listing,  normally  the  line  printer. 

:9$  Console  output,  normally  the  main  operator's  console. 

IR  Network  remote  terminal 

LB  System  library  device,  normally  the  device  from  which 
the  system  was  bootstrapped.  For  example,  LB:  is  the 
device  that  tasks  such  as  TKB  and  MAC  access  for 
default  library  files. 

ML  Null  device. 

HI        Network  pseudo-device  for  NSP. 

NX        Network  pseudo-device  for  DLX. 

RD  On-line  reconfiguration  pseudo-device  (RSX-llN-PLUS 
only) . 

8P        Spooling  scratch  disk  device. 

SY  User  default  device.  On  nonmultiuser  systems,  SY:  is 
normally  the  disk  from  which  the  system  was 
bootstrapped.  On  multiuser  systems,  SY;  is  normally 
the  default  login  device. 

VD        Virtual  Device. 

fl  Pseudo-input  terminal;  TIO:  is  the  terminal  from 
which  a  task  was  requested. 

The  pseudo-device  TI  cannot  be  redirected,  since  such 
redirection  would  have  to  be  handled  on  a  per-task 
rather  than  a  system-wide  basis  (that  is,  change  the  TI 
device  for  one  task  without  affecting  the  TI 
assignments  for  other  tasks) . 

VT  Virtual  terminal.  Used  by  some  RSX-llM-PLUS  offspring 
tasks  as  TI:  for  command  and  data  I/O.  (Supported  in 
RSX-llM-PLUS  systems  only). 


1.7.6  The  GLUN$  Macro:   Retrieving  LON  Inforaation 

The  Get  LUN  Information  macro  requests  that  information  about  a 
LUN-physical  device  unit  association  be  returned  in  a  6-word  buffer 
specified  by  the  issuing  task.  Upon  successful  completion  of  the 
directive  processing,  the  buffer  contains  the  information  listed  in 
Table  1-1,  as  appropriate  for  the  specific  device.  All  three  forms  of 
the  macro  call  may  be  used.  It  is  issued  from  a  MACRO-11  program  in 
the  following  way: 

GLUN$    lun,buf 
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Th«  logical  unit  number  associated  with  the  physical  device   unit 
for  which  information  is  requested. 


The  6-word  buffer  to  which  information  is  returned. 


For  example,  to  request  information  on  the  disk  unit   associated   with 
LUN  8,  the  following  call  is  issued: 

GLUN$C    8.,I0BUP 


Table    1-1 
Get   LUN    Information 


Nuiaarical  Offset 

Syab 

Ollc  Offset 

Contents 

Nord 

Byt* 

Bit 

Mord 

Byte 

Bit 

0 

G.LUNA 

Name  of  device  associated  with 
LUN  (ASCII  bytes) 

I 

0 

1 

G.LUNU 
G.LUPB 

Unit  nunber  of  associated  device 

Driver  flag  value.  Returned  •■ 
200  octal  if  the  driver  is 
resident,  or  as  0  if  a  loadable 
driver  is  not  in  the  systaa 

2 

G.LOCWI 

First  device  characteristics 
word  : 

0 

(O.CWl) 

(DV.REC) 

Unit  rcv-'ord-oriented  device  (for 
exanple,  card  reader,  line 
printer)  (1  ■  yes) 

1 

(DV.CCL) 

Carriage-control  device  (for 
exaaple,  line  printer,  taraiinal) 
(1  ■  yes) 

2 

(DV.TTY) 

Terminal  device  (1  •  yes) 

3 

(DV.DIR) 

Directory  device  (for  esaaipla, 
DBCtape,  disk)  (1  -  yes) 

4 

(DV.SDI) 

Single  directory  device  (for 
example,   ANSI-standard  magtape) 

(1  •  yes) 

5 

(DV.SOD) 

Sequential  device  (for  example, 
ANSI-standard  magtape)  (1  -  yes) 

6 

(DV.MSD) 

Hasa  storage  device  (for  example, 
disks  and  ta,?es)  (1  ■  yes) 

1.    The    following   word   and    bit    symbols   shown    in   parentheses   are   symbols   used    in 
defining  and   referencing  corresponding   items    in   the  device   UCB. 

(continued  on   next   page) 
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Table    l-\      (Cont.) 
Get    LUN    Information 


iNuacriral  Offavt 

Symbolic  Of fast 

Contents 

NOC<) 

Byt* 

Bit 

Word 

Byt* 

Bit 

7 

(DV.UMD) 

User-mode  diagnostics  supported 
(1  -  yes) 

8 

(DV.EXT) 

Device  supports  22~blt  direct 
addressing 

• 

9 

(DV.SWL) 

Unit  software  write-locked 
(1  ■  yes) 

10 

(DV.ISP) 

Input  spooled  device  (1  -  yes) 

11 

(DV.OSP) 

Output  spooled  device  (1  ■  yes) 

12 

(DV.PSE) 

Pseudo-device  (1  >  yes) 

13 

(DV.COM) 

Device  mountable  as  a 
communications  channel  for 
Digital  netv  r|(  support  (fo- 
exampJe,  DPli   DOll)  (1  -  yes) 

14 

(DV.Fll) 

Device  mountable  as  a  PILES-11 
device  (for  example,  disk  or 
DECtape)  (1  -  yes) 

15 

(DV.MNT) 

Device  mountable  (logical  OR  of 
bits  13  and  14)  (1  •  yes) 

3 

G.LOCW+02 
(U.CW2) 

(U2.XXX) 

Second  device  characteristics 
word: 

Devicft-specif ic  information 

4 

G.LUCW'f04 
(U.CW3) 

(03. XXX) 

Third  device  characteristics 
word: 

Device-specific  information^ 

5 

G.LUCW-f06 
(U.CW4) 

• 

Fourth  device  characteristics 
word: 

Default  buffer  size  (fc  example, 
for  disks,  and  line  length  for 
terminals) . 

2.  For  mass  storage  devices,  such  as  disks,  DECtape,  and  DECtape  II,  this  is 
the  number  of  blocks  (maximum  logics  block  number  plus  one)  .  For  the  proper 
use  of  the  RX211/RX02  flexible  disk,  it  is  important  to  be  tible  to  test 
G.L0CW'f4   to  determine  the  media  density. 
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Th«  •xample  included  below  illuatrates  the  use  of  the  three   forms   of 
the  GLUN$  macro. 


;  DATA  DEFINITIONS 

; 

GBTLUN:  GLUN$    6,DSKBUF 


;  GENERATE  DPB 


t 

;  EXECUTABLE  SECTION 

I 

DIR$     tGETLUN 


GLUN$C   6,0SKBUF 


GLUN$S   «6,iDSKBUF 


;  EXECUTE  DIRECTIVE 


;  GENERATE  DPB  IN  SEPARATE  PROGRAM 

;  SECTION,  THEN  GENERATE  CODE  TO 

;  EXECUTE  THE  DIRECTIVE 

;  GENERATE  DPB  ON  STACK,  THEN 

;  EXECUTE  DIRECTIVE 


1.7.7  The  ASTX$S  Macro:   Terminating  AST  Service 

The  AST  Service  Exit  macro  is  used  to  terminate  execution 
service   routine.    All  forms  of  the  macro  are  provided. 
S-form  is  preferred  because  it  requires  less   space   and 
least  as  fast  as  the  ASTX$  or  ASTX$C  form  of  the  macro, 
issued  in  the  following  way: 

ASTX$S   [err] 


of  an  AST 
However ,  the 
executes  at 
The  macro  is 


ecr 

An  optional  argument  which  specifies   the   address   of   an  error 
routine  to  which  control  branches  if  the  directive  is  rejected. 

On  completion  of  the  operation  specified  in  this  macro  call,  if 
another  AST  is  queued  and  asynchronous  system  traps  have  not  been 
disabled,  then  the  next  AST  is  immediately  entered.  Otherwise,  the 
task's  state  before  the  AST  was  entered  is  restored  (it  is  the  AST 
service  routine's  responsibility  to  save  and  restore  the  registers  it 
uses) . 


1.7.8  The  WTSB$  Macro:   Waiting  for  an  Event  Flag 

The  Wait  For  Single  Event  Flag  macro  instructs  the  system  to  suspend 
execution  of  the  issuing  task  until  the  event  flag  specified  in  the 
macro  call  is  set.  This  macro  is  extremely  useful  in  synchronizing 
activity  on  completion  of  an  I/O  operation.  All  three  forms  of  the 
macro  call  may  be  used.   It  is  issued  as  followa: 

WTne   efn 
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•in 


The  event  flag  number. 


WTSB$  causes  the  task  to  be  bloclced  from  execution  until  the  specified 
event  flag  is  set.  Frequently,  an  efn  parameter  is  also  included  in  a 
QIO$  macro  call,  and  the  event  flag  is  set  on  completion  of  the  I/O 
operation  specified  in  that  call.  The  following  example  illustrates 
task  blocking  until  the  setting  of  the  specified  event  flag  occurs. 
This  example  also  illustrates  the  use  of  the  three  forms  of  the  macro 
call. 


> 


DATA  DEFINITIONS 


WAIT: 
lOSB: 


WTSE$    5 
.BtiKW    2 


GENERATE  DPS 
I/O  STATUS  3L0CK 


;  EXECUTABLE  SECTION 

ALUNSS   #14.,#"MM 
QIO$C    10. ATT, 14. ,5 


DIR$ 


QIO$S    tIO.RLB,«14.,«2, ,«IOSB, ,<tBUP,#80.> 

;  READ  RECORD,  USE  EFN2 


NTSE$S   #2 


•WAIT 


ASSIGN  LUN  14  TO  MAGTAPF  UNIT  ZERO 

ATTACH  DEVICE 

EXECUTE  WAITFOR  DIRECT  I'  ■■•, 


;  WAIT  FOR  READ  TO  COMPLETE 


QIO$C    I0.WLB,14. ,3, ,IOSB, ,<BUF,80.> 

;  WRITE  RECORD,  USE  EFN3 


WTSESC   3 


QIO$C    I0.DET,14. 


;  WAIT  FOR  WRITE  TO  COMPLETE 


;  DETACH  DEVICE 


1.8   STANDARD  I/O  rONCTIONS 

The  number  of  input/output  operations  that  can  be  specified  by  means 
of  the  QIO  directive  is  large.  A  particular  operation  can  be 
requested  by  including  the  appropriate  function  code  as  the  first 
parameter  of  a  QIO  macro  call.   Certain  functions  are  standard.   These 
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functions  ar«  alaost  totally  d«vic«  independent  and  can  thus  b* 
requested  for  nearly  every  device  described  in  this  manual.  Others 
are  device  dependent  and  are  specific  to  the  operation  of  only  one  or 
two  I/O  devices.  This  section  sunsiarixes  the  function  codes  and 
characteristics  of  the  following  device- independent  I/O  operations: 

e  Attach  to  an  I/O  device 

e  Detach  from  an  I/O  device 

e  Cancel  I/O  requests 

e  Read  a  logical  block 

e  Read  a  virtual  block 

e  Write  a  logical  block 

e  Write  a  virtual  block 

For  certain  physical  device  units  discussed  in  this  manual,  a  standard 
I/O  funct-ion  may  be  described  as  being  a  NOP.  This  means  that  no 
operation  is  performed  as  a  result  of  specifying  the  function,  and  an 
I/O  status  code  of  IS.SUC  is  returned  in  the  I/O  status  block 
specified  in  the  010  macro  call. 

In  the  following  descriptions  and  in  formats  shown  in  subsequent 
chapters,  the  five  QIO  directive  parameters  lun,  efn,  pri,  isb,  and 
ast  are  represented  by  the  ellipsis  (...)  (see  Section  1.5.1). 


1.8.1   10. ATT:   Attaching  to  an  I/O  Device 

The  function  code  10. ATT  is  specified  by  a  user  task  when  that  task 
requires  exclusive  use  of  an  I/O  device.  This  function  code  is 
included  as  the  first  parameter  of  a  QIO  macro  call  in  the  following 
way: 

0IO$C    10. ATT,... 

Successful  completion  of  an  10. ATT  request  causes  the  specified 
physical  device  unit  to  be  dedicated  for  exclusive  use  by  the  issuing 
task.  This  enables  the  task  to  pr<^cess  input  or  output  in  an  unbroken 
stream  and  is  especially  useful  on  sequential,  non-file-oriented 
devices  such  as  terminals,  card  readers,  and  line  printers.  An 
attached  physical  device  unit  remains  under  control  of  the  issuing 
task  until  it  is  explicitly  detached  by  that  task.  To  detach  the 
device,  the  task  can  specify  any  LUN  previously  assigned  to  the 
attached  device. 

While  a  physical  device  unit  is  attached,  the  I/O  driver  for  that  unit 
dequeues  only  I/O  requests  issued  by  the  task  that  issued  the  attach. 
Thus,  a  request  to  attach  a  device  unit  already  attached  by  another 
task  will  not  be  processed  until  the  attachment  is  broken  and  no 
higher  priority  request  exists  for  the  unit.  A  LUN  that  is  associated 
with  an  attached  physical  device  unit  may  not  be  reassigned  by  means 
of  an  Assign  LUN  directive  except  when  at  least  one  LUN  is  still 
assigned  to  the  attached  device. 
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If  the  task  that  issued  an  attach  function  exits  or  is  aborted  before 
it  issues  a  corresponding  detach,  the  Executive  automatically  detaches 
the  physical  device  unit. 


1.8.2   lO.DET:  Detaching  from  an  I/O  Device 

The  function  code  lO.DET  is  used  to  detach  a  physical  device  unit  that 
has  been  previously  attached  by  means  of  an  10. ATT  request  for 
exclusive  use  of  the  issuing  task.  This  function  code  is  included  as 
the  first  parameter  of  a  QIO  macro  call  in  the  following  way: 

OIOSC    lO.DET,... 

The  LUN  specifications  of  both  10. ATT  and  lO.DET  must  be  the  same,  as 
in  the  following  example,  which  also  illustrates  the  use  of  S-  forms 
of  several  macro  calls. 


.MCALL   ALUN$S,0IOSS 
ALUN$S   #14.,I"CR 


ASSOCIATE  CARD  READER  WITH  LUN  14 


QIOSS    #10. ATT, #14.    ;  ATTACH  CARD  READER 


LOOP:    OIOSS    »I0.RLB,#14. , . . .  ;  READ  CARD 


QIOSS    #I0.DET,#14.    ;  DETACH  CARD  READER 


1.8.3   lO.KIL:  Canceling  I/O  Requests 

The  function  lO.KIL  is  issued  by  a  task  to  cancel  all  of 
I/O  requests  for  a  particular  physical  device  unit. 


that  task's 


For  I/O  requests  waiting  for  service  —  that  is,  in  the  I/O  driver's 
queue  —  a  status  code  of  IE. ABO  is  returned  in  the  I/O  status  block. 
An  event  flag  is  set,  if  specified.  But  any  AST  service  routine  that 
may  have  been  specified  is  not  initiated. 

For  I/O  requests  being  processed  by  an  I/O  driver  —  other  than  the 
disk  or  DECtape  drivers  --  the  IE. ABO  status  code  is  returned.  Other 
status  information  (byte  count,  and  so  forth)  is  also  returned  in  the 
I/O  status  block.   An  AST,  if  specified,  is  activated. 

For  disk,  DECtape,  or  DECtape  II  I/O  requests  being  processed  when  an 
lO.KIL  is  issued,  the  lO.KIL  acts  as  a  NOP.  The  request  is  allowed  to 
complete,  except  in  the  case  in  which  a  DECtape  transfer  is  blocked  by 
a  select  error.  Because  disk  and  DECtape  operate  quickly,  lO.KIL 
simply  causes  the  return  of  IS.SUC  in  the  I/O  status  block. 


as  the  first  parameter  of  a   QIO  macro 


This  function  code  is  included 
in  the  following  way: 

OIOSC    lO.KIL,... 

lO.KIL  is  useful  in  such  special  cases  as  canceling  an  I/O  request  on 
a  physical  device  unit  from  which  a  response  is  overdue  (for  example, 
a  read  on  a  paper  tape  reader). 
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1.8.4   lO.RLBt  Reading  a  Logical  Block 

The  function  code  lO.RLB  is  specified  by  a  task  to  read  a  block  of 
data  from  the  physical  device  unit  specified  in  the  macro  call.  This 
function  code  is  included  as  the  first  parameter  of  a  QIO  macro  in  the 
following  way: 

QIO$C    lO.RLB, . . . ,<stadd,size,pn> 

stadd 

The    starting   address   of   the   data   buffer. 

•  Ize 

The  data  buffer  size  in  bytes. 


pn 


One  to  four  optional  parameters,  used  to  specify  such  additional 
Information  as  block  numbers  for  certain  devices. 


1.8.5   lO.RVB:  Reading  a  Virtual  Block 

The  function  code  lO.RVB  is  used  to  read  a  virtual  block  of  data  from 
the  physical  device  unit  specified  in  the  macro  call.  A  "virtual" 
block  indicates  a  relative  block  position  within  a  file  and  is 
identical  to  a  "logical"  block  for  such  sequential,  record-oriented 
devices  as  terminals  and  card  readers.  For  these  sequential, 
record-oriented  devices,  lO.RVB  is  converted  to  lO.RLB  before  being 
issued. 

NOTE 

Any  subfunction  bits  specified  in  the 
lO.RVB  request  (see  Sections  2.3.1  and 
3.3.1)  are  stripped  off  in  this 
conversion. 

It  is  recommended  that  all  tasks  use  virtual  rather  than  logical 
reads.  However,  if  a  virtual  read  is  issued  for  a  file-structured 
device  (disk,  DECtape,  or  DECtape  II),  the  user  must  ensure  that  a 
file  is  open  on  the  specified  physical  device  unit.  This  function 
code  is  incli'.de<^  as  the  first  parameter  of  a  QIO  macro  call  in  the 
following  way: 

QIOSC    lO.RVB, . . . ,<stadd,slze,pn> 

stadd 

The  starting  address  of  the  data  buffer. 

size 

The  data  buffer  size  in  bytes. 
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pn 

On*  to  four  optional  parameters,  used  to  specify  such  additional 
information  as  block  numbers  for  certain  devices. 


1.8.'^   ][O.WLBt  Writing  a  Logical  Block 

The  Junction  code  lO.WLB  is  specified  by  a  task  to  write  a  block  of 
data  to  the  physical  device  unit  specified  in  the  macro  call.  This 
function  code  is  included  as  the  first  parameter  of  a  QIO  macro  call 
in  the  following  way: 

0IO$C   lO.WLB, . . . ,<stadd,size,pn> 

stadd 

The  starting  address  of  the  data  buffer. 


size 


pn 


The  data  buffer  in  bytes, 


One  to  four  optional  parameters,  used  to  specify  such  additional 
information  as  block  numbers  or  format  control  characters  for 
certain  devices. 


1.8.7   lO.WVB:  Writing  a  Virtual  Block 

The  function  code  lO.WVB  is  used  to  write  a  virtual  block  of  data  to  a 
physical  device  unit.  A  "virtual"  block  indicates  a  block  position 
relative  to  the  start  of  a  file.  For  sequential,  record-oriented 
devices  such  as  terminals  and  line  printers,  the  function  lO.WVB  is 
converted  to  lO.WLB. 


NOTE 


Any  subfunction  bits  specifi 
lO.WVB   request   (see  Section 
3.3.1)   are   stripped   off 
conversion . 


conversion. 


specified  in  the 
2.3.1  and 
in   this 


It  is  recommended  that  all  tasks  use  virtual  rather  than  logical 
writes.  However,  if  a  virtual  write  is  issued  for  a  file-structured 
device  (disk,  DECtape,  or  DECtape  II),  tne  user  must  ensure  that  a 
file  is  open  on  the  specified  physical  device  unit.  This  function 
code  is  included  as  the  first  parameter  of  a  QIC  macro  call  in  the 
following  way: 

QIOSC    lO.WVB, . . . ,<st«dd,size,pn> 

stadd 

The  starting  address  of  the  data  buffer. 
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Sil* 


pn 


The  data  buffer  size  In  bytes. 


■r 


One  to  four  optional  parameters,  used  to  specify  such  additional 
information  as  block  numbers  or  format  control  characters  for 
certain  devices. 


1.8.B  User-Mode  Diagnostic  Functions 

The  I/O  function  code  subfunction  bit,  lO.UMD,  provides  support  for 
user-mode  diagnostics.  To  perform  a  diagnostic  function,  you  must 
s">eclfy  in  the  QIO  directive  parameter  block  the  logical  OR  of  IQ.UMD 
and  the  function  you  want  to  perform.  For  example,  to  perform  a 
diagnostic  Read  Logical  Block  operation,  specify  10. RLB! IQ. UMD  as  the 
I/O  function  code  parameter  to  the  QIO  directive.  You  can  perform 
standard  I/O  functions  such  as  Read  Logical  Block,  Write  Logical 
Block,  Attach  to  Device,  and  Detach  from  Device  in  diagnostic  mode. 

Support  for  user-mode  diagnostics  is  always  present  for  RSX-llM-PLUS, 
but  not  all  drivers  support  user-mode  diagnostic  functions. 
Unpredictable  device  and  driver  behavior  results  when  you  set  the 
IQ.UMD  subfunction  bit  in  Q'lOs  that  are  directed  to  the  device  if  it 
does  not  support  user-mode  diagnostics.  Problems  can  be  avoided  if 
you  do  a  Get  LUN  directive  and  ch^ck  the  user-mode  diagnostics  bit 
before  emitting  the  user-mode  diagnostic  QIO. 

To  support  user-mode  diagnostics,  the  DV.UMD  bit  in  the  UCB  must  be 
set.   DV.UMD  is  at  offset  U.CWl  In  the  UCB. 

In  addition  to  standard  I/O  functions,  RSX-llM-PLUS  provides  the 
following  device-dependent,  user-mode  diagnostic  functions: 

1.   Disk  diagnostic  functions 

lO.HMS       Home  seek  or  recalibrate 

10. ELS       Block  seek  (explicit  seek) 

10. OFF       Offset  position 

lO.RDH       Read  disk  h?ader 

lO.WDH       Write  disk  header 

lO.WCK       Writecheck 
DECtape  diagnostic  functions 

10. RL'       Read  block  number  forward 

lO.RNR       Read  block  number  reverse 
Magtape  diagnostic  functions 

lO.LPC       Read  longitudinal  parity  character 

lO.ERS       Erase  tape 
UMDIOS  is  the  m^To  that  defines  these  functions. 
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To  execute  a  user-mode  diagnostic  function,  you  must  first  attach  for 
diagnostics  using  I/O  function  code  10. ATT! IQ.UMD.  Execute  the 
diagnostic  functions  and  then  detach. 

The  parameter  list  in  words  1  through  ft  of  the  DPB  should  contain  the 
following  information: 

•  I/O  buffer  address 

•  I/O  buffer  size 

•  Offset  factor  for  disks  with  offset  recovery  (to  determine  the 
offset  factor,  refer  to  the  offset  register  in  the  hardware 
reference  manual);  this  parameter  is  not  used  if  the  device 
does  not  have  offset  recovery. 


•  Double-precision  logical  block  number 

•  User's  register  buffet  address  (the  I/O  driver  copies 
hardware  registers  to  this  buffer  in  the  user's  program); 
a  hardware  reference  manual  for  the  length  of  the  address 


its 
see 


A  typical  DPB  for  a  diagnostic  function  might  look  like  the  following: 


.BYTF 

3.12.             ; 

.WORD 

lO.WDHlIO.UMD     ; 

.WORD 

THELUN 

.BYTE 

THEEPN.O          ; 

.WORD 

SIOSTS             ) 

.WORD 

0 

sioauP: 

.WORD 

0 

.WORD 

0 

.WORD 

0 

SLBH:: 

.WORD 

0 

SLBL:: 

.WORD 

0                    ; 

.WORD 

SRGBUF 

SDSKPB: : 

Siz*  of  th«  DPB,  OIOWAIT  directive  cod* 

I/O  function  code 

Loqlcal  Unit  Nunber 

Event  flaq  nunber 

I/O  status  block  address 

AST  address 

Buffer  address 

Transfer  size  in  bytes 

Device  dependent 

Hiqh-order  loqlcal  block  nunber 

Low-order  loqlcal  block  number 

Reqister  buffer  address 

The  user-mode  diagnostic  functions  return  either  Success  (IS.SUC)  or 
Device  Not  Ready  (lE.DNR).  No  other  error  codes  are  returned.  All 
error  recovery  is  completely  up  to  the  user.  Any  errors  that  occur 
will  not  be  logged  in  the  error  log. 

A  typical  program  fragment,  using  the  user-mode  diagnostic  functions, 
might  look  like  the  following: 

.MCALL  UMDIOS,ALUNSS,0IOSS 
UMDIOS  ;  Define  diaqnostic  functions 

AtUNSS   *14.,I*D^,I0  ;  Associate  DM0  with  1 un  14 

OIOSS    *14.,I*DM,I0  ;  Associate  DM0  with  lun  14 


OIOSS    «IO.ATT!I0.UMD,«14. 


;  Attach  DM  for  diaqnostic  I/O 


OIOSS    110. RDHIIO. UMD, IM. ,,,,,<t$I0BUP, 1512. , ,ILBH,tLBL,l$RGHUF>  ;  Read  disk  header 
0IO$S    IIO.RLB! lO.UMD, 114, ,,,, ,<|SI0BUF, 1512. , ,ILBH,«LBL,ISRGBUF>  ;  Read  loqical  block 


OIOSE    »IO.DET!I0.UMD,»14. 


;  Detach  DM 
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1.9   I/O  COMPLETION 


Wh«n  an  I/O  request  has  been  completed,  either  successfully  or 
unsuccessfully,  one  or  mote  actions  may  be  taken  by  the  Executive. 
Selection  of  return  conditions  depends  on  the  parametein  included  in 
the  QIO  macro  call.   There  are  tnree  major  returns: 

1.  A  significant  event  is  declared  on  completion  of  an  I/O 
operation.  If  an  efn  parameter  was  included  in  the  I/O 
request,  the  corresponding  event  flag  is  set. 

2.  If  an  isb  parameter  was  specified  in  the  QIO  macro  call.  a 
code  identifying  the  type  of  success  or  failure  is  return>ad 
in  the  low-order  byte  of  the  first  word  of  the  I/O  status 
block  at  the  location  represented  by  isD. 

This  status  return  code  is  of  che  Lorm  IS.xxx  (success)  or 
IE. XXX  (error).  For  example,  if  the  device  accessed  by  tne 
I/O  request  is  not  ready,  a  status  code  of  lE.DNR  is  returne<1 
in  isb.  The  section  below  (Return  Codes)  summarizes  general 
codes  returned  by  most  of  the  drivers  described  In  this 
manual . 

If  the  isb  parameter  was  omitted,  th^;  requesting  task  cannot 
determine  \7hether  the  I/O  request  was  successfully  completed. 
A  carry  clear  return  from  the  directive  itself  simply  means 
that  the  directive  was  accepteu  and  thj  I/O  request  was 
queued,  not  thuL  the  actual  input/output  operation  was 
successfully  performed. 

3.  If  an  ast  parameter  was  specified  in  the  QIO  mf.cro  call,  a 
branch  to  the  AST  service  routine  that  begins  a:  the  location 
identified  by  ast  occurs  on  completion  of  the  I/O  operation. 
See  Section  1.5.3  for  a  detailed  description  of  AST  service 
routines. 


1.10   RETURN  CODES 

There  are  two  kinds  of  status  conditions   recognized   and   handled   by 
RSX-llM/M-PLUS  when  they  occur  in  I/O  requests: 

•  Directive   conditions,   which   indicate   the    acceptance   or 
rejection  of  the  QIO  directive  itself 

•  I/O  status  conditions,  which  indicate  the  success  or   failure 
of  the  I/O  operation 

Directive  conditions  relevant  to  I/O  operations  may   indicate  any  of 
the  following: 

e  Directive  acceptance 

•  Invalid  buffer  specification 

•  Invalid  efn  parameter 

•  Invalid  lun  parameter 

•  Invalid  DIC  number  or  DPB  size 

•  Unassigned  LUN 

e   Insufficient  memory 
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Si 

A  code  indicating  the  acceptance   or   rejection  of   a  directive 
returned  to  the  Directive  Status  Word  at  symbolic  location  $DSW.   T 
location  can  be  tested  to  determine  the  type  of  directive  condition 
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ymbollcally,  by 
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Binary  values  of  status  codes  always  have  the  following  meanings: 


Code 

Positive  (greater  than  0) 

0 

Negative 


Meaning 

Successful  completion 
Operation  still  pending 
Unsuccessful  completion 


A  pending  opr'ation  means  that  the  I/O  request  Is  still  In  the  queue 
of  requests  for  the  respective  driver,  or  the  driver  has  not  yet 
completely  serviced  the  request. 


1.10.1   Directive  Conditions 


2  summarizes  the  directive  conditions  that  may  be   encountered 
directives.    The   acceptance  condition  is  first,  followed  by 

alphabetical 


Table  1 

in   010  ..._   ^ ._ 

error  codes  Indicating  various  reasons  for  rejection.  In 
order. 


Code 


IS. sue 


lE.ADP 


Table  1-2 
Directive  Conditions 


Reason 


Directive  accepted 

The  first  six  parameters  of  the  QIO  directive  were 
valid,  and  sufficient  dynamic  memory  was  available 
to  allocate  an  I/O  packet.  The  directive  is 
accepted . 

Invalid  address 

The  I/O  status  block  or  the  010  DPB  was  outside  of 
the  Issuing  task's  address  space  or  was  not  aligned 
on  a  word  boundary. 


(continued  on  next  page) 
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Table  1-2   (Cont.) 
Directive  Conditions 


Code 

Reason 

lE.IEF 

Invalid  event  flag  number 

The  efn  specification  in  a  QIO  directive  was   less 

than  0  or  greater  than  96. 

lE.ILU 

Invalid  logical  unit  number 

The   lun   specification   in   a   QIO  directive  was 

invalid   for   the  issuing  task.   For  example,  there 

were  only  5  logical  unit   numbers   associated   with 

the   task,   and   the   value   specified   for  lun  was 

greater  than  5. 

lE.SDP 

Invalid  DIG  number  or  DPB  size 

The  directive  identification  code  (DIG)  or  the  size 

of   the   Directive    Parameter   Block   (DPB)   was 

incorrect;   the  legal  range  for  a   DIG   is   from   1 

through   127,  and  all  DIG  values  must  be  odd.   Each 

individual  directive  requires  a  DPB  of  a  certain 

size.     If   the   size   is   not  correct   for   the 

particular  directive,  this  code  is   returned.    The 

size  of  the  QIO  DPB  is  always  12  words. 

lE.ULN 

Unassigned  LUN 

The  logical  unit  number  in  the  QIO     directive  was 

not   associated   with   a  physical  device  unit.   The 

user  may  recover  from  this  error  by  issuing  a  valid 

Assign    LUN   directive  and   then   reissuing   the 

rejected  directive. 

lE.UPN 

Insufficient  dynamic  memory 

There  was  not  enough  dynamic  memory  to  allocate  an 

I/O  packet   for  the  I/O  request.   The  user  can  try 

again  later  by  blocking  the   task   with   a  Waitfor 

Significant   Event  directive.    Note   that  Waitfor 

Significant  Event  is  the  only  effective  way  for  the 

issuing   task   to  block  Its  execution,  since  other 

directives  that  could   be   used   for   this  purpose 

themselves   require   dynamic   memory   for   their 

execution  (for  example,  Mark  Time). 

1.10.2   I/O  Status  Conditions 

The  following  list  summarizes  status  codes  that  may  be  returned  in  the 

I/O  status  block  specified  in  the  QIO  directive  on  completion  of  the 

I/O  request.   The  I/O  status   block   is  a   2-word   block  with   the 
following  format: 

•  The  low-order  byte  of  the  first  word  receives  a  status  code  of 
the  form  IS.xxx  or  lE.xxx  on  completion  of  the  I/O  operation. 

•  The  high-order  byte  of  the  first  word  is  usually  device 
dependent;  in  cases  where  the  user  might  find  information  in 
this  byte  helpful,  this  manual  identifies  that  information. 
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•  The  second  word  contains  the  number  of  bytes  transferred  or 
processed  if  the  operation  is  successful  and  involves  reading 
or  writing. 

If  the  isb  parameter  of  the  QIO  directive  is  omitted,  this  information 
is  not  returned. 


The   following   illustrates   a   sample   2-word   I/O  status  block  on 
completion  of  a  terminal  read  operation: 


Word  0 


1 


1 

0                        B 

0 

-10 

Number    of   bytes   read 

Byte 


where  -10  is  the  status  code  for  IE. EOF  (end  of  file).  If  this  code 
is  returned,  it  indicates  that  input  was  terminated  by  typing  CTRL/Z, 
which  is  the  end-o£-file  termination  sequence  on  a  terminal. 

To  test  for  a  particular  error  condition,  the  user  generally  compares 
the  low-order  byte  of  the  first  word  of  the  I/O  status  block  with  a 
symbolic  value,  as  in  the  following: 


CMPB 


#IE.DNR,IOSB 


However,  to  test  for  certain  types  of  successful  completion  of  the  I/O 
operation,  the  entire  word  value  must  be  compared.  For  example,  if  a 
carriage  return  terminated  a  line  of  input  from  the  terminal,  a 
successful  completion  code  of  IS.CR  is  returned  in  the  I/O  status^ 
block.  If  an  Escape  (or  Altmode)  character  was  the  terminator,  a  code 
of  IS. ESC  is  returned.  To  check  for  these  codes,  the  user  should 
first  test  the  low-order  byte  of  the  first  word  of  the  block  for 
IS. sue  and  then  test  the  full  word  for  IS.CC,  IS.CR,  IS. ESC,  or 
IS. ESQ.  (Other  success  codes  that  must  be  read  in  this  manner  are 
listed  in  Appendix  B,  Section  B.1.2.) 


Note  that  both  of  the  following  comparisons  will  test  as  equal 
the  low-order  byte  in  both  cases  is  +1. 


since 


CMP     #IS.CR,IOSB 

CMPB    #IS.SUC,IOSB 

In  the  case  of  a  successful  completion  where  the  carriage  return  is 
the  terminal  indicator  (IS.CR),  the  following  illustrates  the  status 
block: 


1 


Byte 


Word  0 


15 


♦1 


Number  of  bytes  read 
(excluding  the  CR) 


wheie  15  is  the  octal  code  for  carriage  return  and  +1   is 
code  for  successful  completion. 


the   status 


The  codes  described  in  Table  1-3  are  general  status  codes  that  apply 
to  the  majority  of  devices  presented  in  subsequent  chapters.  Error 
codes  specific  to  only  one  or  two  drivers  are  described  only  in 
relation  to  the  devices  for  which  they  are  returned.  The  list  below 
describes  successful  and  pending  codes  first,  then  error  codes  in 
alphabetical  order. 
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Table  1-3 
I/O  Status  Conditions 


Code 

Reason 

IS. sue 

Successful  completion 

The  I/O  operation  specified  in  the  010  directive 
was  completed  successfully.  The  second  word  of  the 
I/O  status  block  can  be  examined  to  determine  the 
number  of  bytes  processed,  if  the  operation 
Involved  reading  or  writing. 

IS.PND 

I/O  request  pending 

The  I/O  operation  specified  In  the  010  directive 
has  not  yet  been  executed.  The  I/O  status  block  is 
filled  with  08. 

I  E.ABO 

Operation  aborted 

The  specified  I/O  operation  was  cancelled  with 
lO.KIL  while  in  progress  or  while  still  in  the  I/O 
queue. 

lE.ALN 

File  already  open 

The  task  attempted  to  open  a  file  on  the  physical 
device  unit  associated  with  the  specified  LUN,  but 
a  file  has  already  been  opened  by  the  issuing  task 
on  that  LUN. 

IE. BAD 

Bad  parameter 

An  illegal  specification  was  supplied  for  one  or 
more  of  the  device-dependent  QIO  parameters  (words 
fi-Il).  For  example,  a  bad  channel  number  or  gain 
code  was  specified  in  an  analog-to-digital 
converter  I/O  operation. 

lE.BBE 

Bad  block  on  device 

One  or  more  bad  blocks  were  found  by  executing  the 
BAD  utility.   Data  cannot  be  written  on  bad  blocks. 

lE.BLK 

Illegal  block  number 

An  illegal  block  number  was  specified  for  a 
file-structured  physical  device  unit.  This  code  is 
returned,  for  example,  if  block  4800  is  specified 
for  an  RKn5  disk,  on  which  legal  block  numbers 
extend  from  0  through  4799. 

IE. BYT 

Byte-alignad  buffer  specified. 

Byte  alignment  was  specifi^c  Tor  a  buffer,  but  only 
word  (or  double-word)  al.  nment  is  legal  for  the 
physical  device  unit.  Foi  .k^ample,  a  disk  function 
requiring  word  align  .ent  was  requested,  but  the 
buffer  was  aligned  on  a  byte  boundary. 
Alternately,  the  length  of  a  buffer  was  not  an 
appropriate  multiple  of  bytes.  For  example,  all 
RP03  disk  transfers  must  be  an  even  multiple  of 
four  bytes. 

(continued  on  next  page) 


l-3*> 


RSX-llM/H-PLUS  INPUT/OUTPUT 


Table 
I/O  Sta'. 


1-3   (Cont.) 
us  Conditions 


Code 


Reason 


lE.DAA 


lE.DNA 


lE.DNR 


IE. EOF 


lE.FHE 


Device  already  attached 

The  physical  device  unit  specified  in  an  10. ATT 
function  was  already  attached  to  the  issuing  task. 
This  code  indicates  that  the  Issuing  task  has 
already  attached  the  desired  physical  device  unit, 
not  that  the  unit  was  attached  by  another  task. 

Device  not  attached 

The  physical  device  unit  specified  in  an  lO.UET 
function  was  not  attached  to  the  Issuing  task. 
This  code  has  no  bearing  on  the  attachment  status 
with  respect  to  other  tasks. 

Device  not  ready 

The  physical  device  unit  specified  in  the  QIO 
directive  was  not  ready  to  perform  the  desired  I/O 
operation.  This  code  is  often  returned  as  the 
result  of  an  interrupt  time-oJt;  that  is,  a 
"reasonable"  amount  of  time  has  passed,  ^"'^  the 
physical  device  unit  has  not  responded. 


End-of-file  encountered 

An  end-of-file  mark,  record,  or   control 
was  recognized  on  the  input  device. 

Fata',  hardware  error 


character 


IE. IPC 


Controller  is  physically  unable  to  reach  the 
location  where  input/output  is  to  be  performed  on 
the  device.   The  operation  cannot  be  completed. 

Illegal  function 

A  function  code  was  specified  in  an  I/O  request 
that  was  illegal  for  the  specified  physical  device 
unit.  This  code  is  returned  if  th^  task  attempts 
to  execute  an  illegal  function  or  if,  for  example, 
a  read  function  Is  requested  on  an  output-only 
iJevice,  such  as  the  line  printer. 


lE.NLN 


IE. NOD 


File  not  open 

The  task  attempted  to  close  a  file  on  the  physical 
device  u'llt  associated  with  the  specified  LUN,  but 
no  file  was  currently  open  on  that  LUN. 

Insufficient  buffer  space 

Dynamic  storage  space  has  been  depleted,  and  there 
was  insufficient  buffer  space  available  to  allocate 
a  secondary  control  block.  For  example,  if  a  task 
attempts  to  open  a  file,  buffer  space  ioi  the 
window  and  file  control  block  must  be  supplied  by 
the  Executive.  This  code  is  returned  when  there  is 
no;  enough  space  for  such  an  operation. 

(continued  on  next  page) 
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Table  1-3   (Cont.) 
I/O  Status  Conditions 


Cod* 

Reason 

lE.OFL 

Device  off  line 

The  physical  device  unit  associated   with   the   LUN 

specified   in   the   QIO   dli««ctive  was  not  on  line. 

When   the   system  was   booted,   a    device   check 

indicated  that  this  physical  device  unit  was  not  in 

the  configuration. 

lE.OVR 

Illegal  read  overlay  request 

A  read   overlay   was   requested   and   the   physical 

device   unit  specified  in  the  QIO  directive  was  not 

the  physical  device  unit  from  which   the   task   was 

installed.    The   read  overlay  function  can  only  be 

executed  on  the  physical  device  unit  from  which  the 

task  image  containing  the  overlays  was  Installed. 

lE.PRI 

Privilege  violation 

The  task  that  issued  a  request  was   not   privileged 

to   execute   that   request.    For   example,  for  the 

UDCll  and  LPSll,  a  checkpointable  task  attempted  to 

connect   to   interrupts  or  to  execute  a  synchronous 

sampling  function. 

lE.SPC 

Illegal  address  space 

The  buffer  lequested  for  a  read   oi   write   request 

was   partially  or  totally  outside  the  address  space 

of  the  issuing  task.   Alternately,  a  byte  count   of 

0  was  specified. 

lE.VER 

Unrecoverable  err'^r 

After  the  system's  standard  number  of  retries   have 

been   attempted   upon   encountering   an   error,  tne 

operation  still  could  not  be  completed.   This   code 

is   returned  In  the  case  of  parity,  CRC,  or  similar 

errors. 

lE.WCK 

Write  check  error 

An  error   was   detected   during   the   check   (read) 

following  a  write  operation. 

lE.WLK 

Write-locked  device 

The  task   attempted   to   write   on   a   wrlte-locked 

physical  device  unit. 
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1.11   POWER-FAIL  RECOVERY  PROCEDURES  FOR  DISKS  AND  DECTAPE 

Power-fall  recovery  recommendations  for  various  devices  are  included 
in  the  following  chapters,  as  appropriate,  to  assist  the  user  in 
restoring  device  operation  after  a  power  failure.  For  disks  and 
DECtape,  it  is  recommended  that  power  recovery  ASTs  be  used.  The  AST 
service  routine  should  provide  a  sufficient  time  delay,  prior  to 
returning  for  normal  I/O  operations,  that  will  allow  the  disk  to 
attain  normal  operating  speed  before  actually  attempting  read  and 
write  operations. 

If  OIOs  are  being  used  for  disk  or  DECtape  I/O  operations  during 
power-fail  recovery,  an  lE.DNR  error  status  may  be  returned  if  the 
device  is  not  up  to  operating  speed  when  the  request  is  issued.  When 
this  error  is  returned,  it  is  recommended  that  the  user  task  wait  a 
sufficient  time  for  the  device  to  attain  operating  speed,  and  attempt 
the  I/O  operation  again  prior  to  reporting  an  error.  For  example,  an 
RK05  disk  may  require  approximately  1  minute  to  attain  operating  speed 
after  a  power  failure. 
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POLL-DOPLBX  TERMINAL  DRIVER 


2.1   IMTRODOCTION 

Two  terminal  drivers  are  available   as  SYSGEN  options   for   use   in 
RSX-llH  sy&tems: 

1.  A  compact,  half-duplex  terminal  driver  for  use  with  a  wide 
variety  of  terminals,  containing  all  basic  features  required 
for  RSX-llN  terminal  support.  (This  terminal  driver  is  not 
available  on  RSX-llM-PLUS  systems.)  This  terminal  driver  is 
described  in  Chapter  3. 

2.  A  full-duplex  terminal  driver,  as  described  in  this  chapter, 
containing  all  features  of  the  half-duplex  terminal  driver, 
plus  the  following: 

•  Full-duplex  operation 

•  Type-ahead  buffering 

•  Eight-bit  characters 

•  Detection  of  hard  receive  errors 

•  Increased  byte  transfer  length  (8128  bytes] 

•  Additional  terminal  characteristics 

•  Additional  terminal  types 

•  Optional  time-out  on  solicited  and/or  unsolicited  input 

•  Device-independent  cursor  control 

•  Redisplay  of  prompt  buffer  upon  CTRL/R  or  CTRL/U 

•  Automatic  XOFF  character  generation  upon  completion   of   a 
read  (except  when  in  the  full-duplex  mode) ,  if  requested 

•  Autobaud  speed  detection 

•  Added  hardware  support 

Note  that  either  terminal  driver  can  be  selected  during  RSX-llM 
SYSGEN.  RSX-llM-PLUS  systems  use  the  full-duplex  terminal  driver 
only. 
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Throughout  the  remainder  of  this  chapter,  references  made  to  MCR  can 
generally  be  applied  to  other  command  line  interpreters  (for  example, 
DCL) .  In  addition,  the  prompt  displayed  on  a  terminal  in  response  to 
invoking  a  command  line  interpreter  will  be  appropriate  for  the 
specific  command  line  interpreter  in  use.  For  example,  when  HCR  is 
invoiced,  the  MCR  prompt  is  displayed  as  follows: 

MCR> 

Terminal  driver  support  is  provided  for  a  variety  of  terminal  devices, 
as  listed  in  Table  2-1.  Subsequent  sections  describe  each  device  in 
greater  detail. 


Table  2-1 
Supported  Terminal  Devices 


Model 

Columns 

Lines/, 
Screen 

Character 
Set 

Baud 
Range 

Upper-  fc 

Lowercase? 

Send 

Receive 

ASR-33/35 

72 

64 

.10 

KSR-33/35 

72 

64 

110 

LA12 

132 

96 

50-9600 

yes 

yes 

LAIOO 

132 

96 

110-9600 

yes 

yes 

LA30-P 

80 

64 

300 

LA30--S 

80 

64 

110-300 

LA34 

132 

96 

110-300 

yes 

yea 

LA36 

132 

64-96 

110-300 

yes 

yes^ 

LA38 

132 

96 

110-300 

yes 

yes 

LA120 

132 

0 

50-9600 

yes 

yes 

LA180S 

132 

96 

300-9600 

yes 

LQP02 

132/158 

110-9600 

LA50 

80/96/132 

110-4800 

RT02 

64 

1 

64 

110-1200 

RT02-C 

64 

1 

64 

110-1200 

VT05B 

72 

20 

64 

110-2400 

yes 

VT50 

80 

12 

64 

110-9600 

VT50H 

80 

12 

64 

110-9600 

VT52 

80 

24 

96 

110-9600 

yes 

yes 

VT55 

80 

24 

96 

110-9600 

yes 

yes 

VT61 

80 

24 

96 

110-9600 

yes 

yes 

VTIOO 

80-132 

24 

96 

50-9600 

yes 

yes 

VTlOl 

80-132 

24 

96 

50-19200 

yes 

yes 

VT102 

80-132 

24 

96 

50-9600 

yes 

yes 

VT105 

80-132 

24 

96 

50-19200 

yes 

yes 

VT125 

80-132 

24 

96 

50-9600 

yes 

yes 

VT131 

80-132 

24 

96 

50-19200 

yes 

yes 

VT132 

80-132 

24 

96 

50-19200 

yes 

yes 

• 


1.  Applies  only  to  video  terminals. 

2.  Only  for  96-character  terminal.  The  terminal  driver  supports  the 
terminal  interfaces  summarized  in  Table  2-2.  These  interfaces  are 
described  in  greater  detail  in  Section  2.9.  Programming  is  identical 
for  all  interfaces. 
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Table  2-2 
Standard  Terminal  Interfaces 


Model 

Type 

DHll 

DHVll 

DHll-DMll-BB 

DJll 

DLll-A/B/C/D/E/W 

DLVll-E/F 

DZll 

16-line  multiplexer^ 

8-line  multiplexer^ 

16-line  multiplexer  with  modem  control^ 

16-line  multiplexer 

Single-line  interfaces 

Single-line  interfaces^ 

8-line  multiplexer  with  modem  control^ 

1.  Direct   memory   access   (DMA)    is 
full-duplex  terminal  driver  only. 


supported   in   the 


2.  Full-duplex  control  only.   For  example,  in   the   USA,  a 
Bell  103A-type  modem. 

3.  DLVll  and  DHVll  support  with  modem  control  is  provided 
in  the  full-duplex  terminal  driver  only. 


Terminal  input  lines  can  have  a  maximum  length  of  8128  (8K  minus  64) 
bytes.  Extra  characters  of  an  input  line  that  exceed  the  maximum  line 
length  generally  become  an  unsolicited  input  line  if  the  terminal  is 
not  attached  with  typeahead  enabled. 


2.1.1  ASR-33/35  Teletypes* 

The  ASR-33  and  ASR-35  Teletypes  are  asynchronous,  hard-copy  terminals. 
No  paper-tape  reader  or  punch  capability  is  supported. 


2.1.2  KSR-33/35  Teletypes* 

The  KSR-33  and  KSR-35  Teletypes  are  asynchronous,  hard-copy  terminals, 

2.1.3  LA12  Portable  Terminal 

The  LA12  is  a  personal,  portable,  hard-copy  terminal. 

2.1.4  LAIOO  DECpr inter 

The  LAIOO  is  a  desk-top,  matrix,  hard-copy  terminal. 

1.  Teletype  is  a  registered  trademark  of  the  Teletype  Corporation. 
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2.1.5  LA30  DBCwcltara 

The  LA30  DECwrlter  is  an  asynchronous,  hard-copy  tsrminal  that  is 
capable  of  producing  an  original  and  one  copy.  The  LA30-P  is  a 
parallel  model  and  the  LA30-S  is  a  serial  model. 


2.1.6   LA3e  DICwriter 

The  LA36  DECwriter  is  an  asynchronous  terminal  that  produces  hard  copy 
and  operates  in  serial  mode.  It  has  an  impact  printer  capable  of 
generating  multipart  and  special  preprinted  forms.  The  LA36  can 
receive  and  transmit  both  uppercase  and  lowercase  characters. 


2.1.7   LA34/38  DBCwr iters 

The  LA34  DECwriter  is  an  asynchronous  terminal  that  produces  hard  copy 
and  uses  a  platen  paper  feed  mechanism. 

The  LA38  DECwriter  includes  a  detachable  tractor   feed  mechanism   for 
use  with  continuous  forms. 


2.1.6   LA120  DECwriter 


The  LA120  DECwriter  is  a  hard-copy,   upper- 
capable   of    printing   multipart    forms 
characters-per-second.   Serial  communication 
14  baud  rates  ranging  from  50  to  9600  bps; 
baud  rates  are  supported  by  the  terminal   dr 
allow   bidirectional   printing   for   maximum 
allow  user-selected  features,  including  font 
margins,  and  forms  control.   These  functions 
system  by  issuing  appropriate  ANSI-standard 


and   lowercase   terminal, 

at    speeds   up   to   180 

s  speed  is   selected   from 

split  transmit  and  receive 

iver.    Hardware   features 

printing  speed,  and  also 

size,  line  spacing,  tabs, 

can  also  be  set  up  by  the 

escape  sequences. 


2.1.9   LA180S  DECpr inter 

The  LA180S  DECprinter  is  a  serial  version  of  the  LA180.  It  is  e 
print-only  device  (it  has  no  keyboard)  thdt  can  generate  multipart 
forms.   The  LA180S  can  print  uppercase  and  lowercase  letters. 


2.1.9A  LOP02  Letter-Quality  Printer 

The  LQP02  Letter-Quality  Printer  is  a  formed  character,  desktop 
printer  incorporating  daisywheel  technology.  This  letter-quality 
printer  offers  over  100  character  sets  and  handles  regular  office 
stationery  up  to  a  maximum  of  15  inches,  but  the  print  capacity  is 
13.5  inches.  The  lines  per  inch  and  characters  per  inch  are  software 
selectable:  characters  at  10  and  12  and  lines  at  2,  3,  4,  6,  and  8. 
At  10  characters  per  inch  you  get  132  columns  and  at  12  characters  you 
get  158  columns.   The  buffer  capacity  is  256  characters. 
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2.1.9B   LA50  Personal  Ptlntar 

Th«  LA50  Personal  Printsr  is  a  dssktop  dot-matrix  impact  printer.  It 
has  two  print  modes;  text  mode  and  enhanced  print  mode.  In  text 
mode,  it  prints  at  100  characters  pet  second.  The  enhanced  print 
quality  mode  prints  at  50  characters  per  second  and  creates  a  crisper, 
more  uniform  character  than  an  ordinary  dot-matrix  printer.  You  can 
choose  characters  per  inch  at  10,  12,  or  16  which  gives  columns  at  80, 
96,  or  132  and  lines  per  inch  can  be  6,  8,  or  12.  The  buffer  capacity 
is  255  characters. 


2.1.10  RT02  Alphanuaeric   Display   Terminal   and   IIT02-C   Badge 
Reader /Alphrnuaerlc  Display  Terminal 

The  RT02  is  a  compact,   alphanumeric  display   terminal   designed   for 
applications   in   which  source  data  is  primarily  numeric.   ^  shift  key 
permits  the  entry  of   30    discrete   characters,   including   uppercase 
alphabetic  characters.   The  RT02  can,  however,  receive  and  display  64 
characters . 

The  RT02-C  model  also  contains  a  badge  reader.  This  option  provides  a 
reliable  method  of  identifying  and  controlling  access  to  the  PDP-11  or 
to  a  secure  facility.  Fur  therrrore ,  data  in  a  format  corresponding  to 
that  of  a  badge  (^.'^-column  fixed  data)  can  be  entered  quickly. 
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2.1.11   VT05B  Alphanuacrlc  Display  Tvrnlnal 

The  VTOSB  is  an  alphanumeric  display  terminal  chat  consists  of  a  CRT 
display  and  a  self-contained  keyboard.  Prom  a  programming  point  of 
view,  it  is  equivalent  to  other  terminals,  except  that  the  VTOSB 
offers  direct  cursor  addressing. 


2.1.12  VTSO  Alphanumeric  Display  Terminal 

The  VTSO  is  an  alphanumeric  display  terminal  that  consists  of  a  CRT 
display  and  a  keyboard.  It  is  similar  to  the  VTOSB  in  operation,  but 
does  not  offer  direct  cursor  addressing. 


2.1.13  VT50H  Alphanumeric  Display  Terminal 

The  VT50H  is  an  alphanumeric  display  terminal  with  CRT  display, 
keyboard,  and  numeric  pad.  It  offers  direct  cursor  addressing.  (The 
VTSOH's  direct  cursor  addressing  Is  not  compatible  with  that  of  the 
VTOSB.) 


2.1.14  VT52  Alphanumeric  Display  Terminal 

The  VT52  is  an  upper-  and  lowercase  alphanumeric  terminal  with  numeric 
pad  and  direct  cursor  addressing.  (The  VT52*s  direct  cursor 
addressing  is  compatible  with  that  of  the  VT50H,  not  with  that  of  the 
VTOSB.)  The  VT52  can  be  configured  with  a  built-in  thermal  printer. 


2.1. IS  VTS5  Graphics  Display  Terminal 

The  VTS5  is  similar  to  the  VTS2  in  its  operation  as  an  alphanumeric 
terminal.  The  VTS5  offers  graphics  display  features  that  are  not 
supported  by  RSX-llM,  although  the  system  allows  a  knowledgeable  task 
to  access  the  explicitly  special  features  of  the  VTSS. 


7.\.\fi     VT61  Alphanumeric  Display  Terminal 

The  VTfil  is  an  "intelligent"  upper-  and  lowercase  alphanumeric 
terminal  with  an  Integral  microprocessor.  It  offers  two  128-member 
character  sets  and  numerous  built-in  functions  for  editing  and  forms 
preparation  as  well  as  a  block-transfer  mode.  (None  of  these  special 
features  is  supported  by  RSX-llM.) 


2.1.17  VTIOO  DECscope 

The  VTIOO  DECscope  is  an  upper-  and  lowercase  alphanumeric 
keyboard/video  display  terminal.  It  is  capable  of  displaying  24  lines 
of  80  to  132  characters  (each  line).  Serial  communications  speed  is 
selected  from  baud  rates  ranging  from  50  to  9600  bps.  Hardware 
features  allow  user  selection  of  display  characteristics  and  functions 
including  smooth  scroll,  reverse  video,  and  so  forth.  These  functions 
can  also  be  set  up  by  die  system  by  issuing  appropriate  ANSI-standard 
escape  sequences. 
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■?.1.18   VTlOl  DECscope 

Th«  VTlfll  DECscope  is  functionally  identical  to  the   VTIOO,    Ho\n^9t r 
it  does  not  support  the  advanced  video  features. 


2.1.19   VT102  DECscope 

The  VT102  DECscope  is  functionally  identical  to  the  VTIOO.  However, 
it  does  not  have  any  expansion  capability  and  does  not  support  the 
advanced  video  features.  It  has  enhanced  modem  control  and  it 
Includes  a  port  for  a  printer. 


2.1.20   VT105  DECscope 

The  VT105  DECscope  is  a  video  terminal.  It  has  both  alphanumeric  and 
graphic  display.  The  VT105  can  display  two  graphs,  two  shaded  graphs, 
or  two  strip  charts.   These  graphs  may  have  alphanumeric  labels. 


2.1.21   VT131  DECscope 

The  VT131  is  the  same  as  the   VT102   with   the   addition   of   built-in 
editing  features. 


2.2   GET  LUN  INFORMATION  MACRO 

Word  2  of  the  buffer  filled  by  the  Get  LUN  Information  system 
directive  (the  first  characteristics  word)  contains  the  following 
information  for  terminals.  A  setting  of  1  indicates  that  the 
described  characteristic  is  true  for  terminals. 


•it 

0 


Setting 
1 
1 
1 
0 
0 
0 
0 
0 
0 
0 


Meaning 
Record-oriented  device 
Carriage-control  device 
Terminal  device 
File  structured  device 
Single-directory  device 
Sequential  device 
Mass  storage  device 
User-mode  diagnostics  supported 
Device  supports  22-bit  direct  addressing 
Unit  software  write-locked 
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Meaning 

Input  spooled  device 

Output  spooled  device 

Pseudo  device 

Device  mountable  as  a  communications 
channel 

Device  mountable  as  a  PILES-11  volume 

Device  mountable 

Words  3  and  4  of  the  buffer  are  undefined.  Word  5  Indicates  the 
default  buffer  size  (the  width  of  the  terminal  carriage  or  display 
screen) . 


Bit 

Setting 

10 

11 

12 

13 

14 

15 

0 

2.3   010  MACRO 

Table  ?-3  lists  the  standard  and  device-specific  functions  of  the  QIO 
macro  that  are  valid  for  terminals.  Some  device-specific  functions 
are  options  that  may  be  selected  during  SYSGEN. 

Two  device-specific  functions,  SF.SMC  and  SF.GMC,  have  nonstandard 
function  names.  These  names  are  retained  for  compatibility  with 
RSX-llD. 


Table  2-3 
Standard  and  Device-Specific  QIO  Functions  for  Terminals 


Format 

Function 

STANDARD  FUNCTIONS: 

OIOSC 

in,A':"r,  .  .  . 

Attach  device. 

QIOSC 

lO.DET,.. . 

Detach  device. 

OIOSC 

lO.KIL,. . . 

Cancel  I/O  requests. 

OIOSC 

lO.RLB^ . . . ,<stadd ,size[ ,tmo] > 

READ  logical  block 
(read  typed  input  into 
buffer)  . 

OIOSC 

lO.RVB, . . . ,<stadd,3ize[ ,tmo] > 

READ  virtual  block 
(read  typed  input  into 
buffer)  . 

OIOSC 

lO.WLB, . . . ,<stadd,size,vfc> 

WRITE  logical  block 
(print  buffer 
contents)  . 

OIOSC 

lO.WVB, . . . ,<stadd ,size,vfc> 

WRITE  virtual  block 
(print  buffer 
contents) . 

(continued  on  next  page) 
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Tabl*  2-3   (Cont.) 
Standard  and  0«vic«-Sp«clf ic  010  Punctiona  for  Tarmlnals 


Format 

Function 

DEVICE-SPECIFIC  FUNCTIONS: 

0IO$C  lO.ATA, ...,<aat, 

fparaineter21  [,aat21>l 

ATTACH  device,  apecify 
unaoliclted-input- 
character  AST. 

0IO$C  lO.CCO, . . . ,<8tadd,aiza,vfc> 

CANCEL  CTRL/0  (if  in 
effect) ,  then  write 
logical  block. 

OIOSC  SF.GMC,. . .,<8tadd,8ize>l 

GET  multiple 
characteristics. 

OIOSC  I0.GTS,...,<atadd,8iz«>l 

GET  terminal  support. 

OIOSC  lO.HNG,... 

HANGUP  remote  line. 

OIOSC  lO.RAL, .  . .  ,<8tadd,8l2er  ,tino]> 

READ  logical  block, 
pas3  all  bits. 

OIOSC  lO.RNE,. .. ,<3tadd,size[,tmol> 

READ  logical  block,  do 
not  echo. 

QIOSC  lO.RPR,. . . ,<8tadd,size, 

ftmoj ,pradd,prslze,vfc>l 

READ  logical  block 
after  prompt. 

OIOSC  lO.RST,. . . ,<stadd,size[,tmo1> 

READ  logical  block 
ended  by  special 
terminators. 

OIOSC  I0.RTT,...,<3tadd,size, 
rtmol ,table> 

READ  logical  block 
ended  by  specified 
special  terminator. 

OIOSC  SF.SMC, .. .,<stadd,slze>l 

SET  multiple 
characteristics. 

OIOSC  lO.WAL, . . . ,<stadd,size,vfc> 

WRITE  logical  block, 
pass  all  bits. 

QIOSC  lO.WBT, . . . ,<stadd,size,vfc>l 

WRITE  logical  block, 
break  through  any  I/O 
conditions  at 
terminal . 

ast 


The  entry  point  for  an  unsolicited-  input-character  AST. 


parameter  2 


A  number  that  can  be  used  to  identify  this  terminal  as  the   input 
source  upon  entry  to  an  unsolicited  character  AST  routine. 


1.  SYSGEN  options  in  RSX-llM. 
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••t2 


Th«  antry  point  for  an  unsolicited  CTRL/C  AST, 


pradd 


Th«  starting  address  of  th«  byte  buffer  where  the  prompt  is 
stored. 


praise 


The  site  of  the  pradd  prompt  buffer  In  bytea.  The  specified  site 
must  be  greater  than  0  and  leas  than  or  equal  to  8128.  The 
buffer  muat  be  within  the  task's  addresa  apace. 


sise 


The  size  of  the  stadd  data  buffer  in  bytes.  The  specified  size 
must  be  greater  than  0  and  less  than  or  equal  to  8128.  The 
buffer  must  be  within  the  task's  address  space.  For  SF.GMC, 
10. GTS,  and  SF.SMC  functions,  size  must  be  an  even  value. 


stadd 


The  starting  address  of  the  data  buffer.  The  address  must  be 
word  aligned  for  SF.GMC,  10. GTS,  and  SF.SMC;  otherwise,  stadd 
may  be  on  a  byte  boundary. 


table 


taio 


The  address  of  the  16-word  special  terminator  table. 


vfc 


An  optional  time-out  count  in  10-second  intervals  for  the 
full-duplex  terminal  driver.  If  0  is  specified,  no  time-out  can 
occur.  Time-out  is  the  maximum  time  allowed  between  two  input 
characters  before  the  cead  is  aborted.  The  maximum  timeout  value 
is  255. 


A  character  for  vertical  format 
Section  2.7) . 


control   from  Table  2-11   (see 


2.3.1  Subf unction  Bits 

Most  device-specified  functions  supported  by  terminal  drivers 
described  in  this  section  are  selected  using  "subf unction  bits."  One 
or  more  functions  can  be  selec*-ed  by  ORing  their  relative  bits  in  a 
QIO  function.  Table  2-4  contains  a  listing  of  QIO  functions  and 
relative  subfunction  bits  that  can  be  issued. 
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Each  subfunctlon  bit  and  subfunctlon  aalected  whan  it  ia  included  in  a 
QIC  function  ia  liatod  aa  followa: 

8yad>olic 

NaiM  Sub function 

TP.AST  Unaolici ted-input-charactar  AST 

TF.BIN  Binary  prompt 

Tif.CCO  Cancel  CTRL/0 

TF.ESQ  Recognize  escape  aequencea 

TF.NOT  Unaolicited  input  AST  notification;   unsolicited 

characters   are   stored  in  the  type-ahead  buffer 

until  they  are  read  by  the  task 
TF.RAL  Read  all  bits 

TF.RCU  Restore  cursor  position 

TF.RNE  Read  with  no  echo 

TF.RST  Read  with  special  terminators 

TF.TMO  Read  with  time-out 

TF.WAL  Write  all  bits 

TF.WBT  Break-through  write 

TF.XCC  CTRL/C  starts  a  command  line  interpreter  commoni 

line   (Command   line   characters  are  not  sent  to 

the  task.) 
TF.XOF  Send  XOFF 

Table  2-4  lists  subfunction  bits  that  can  be  ORed  with  QIO  functions. 
Additional  details  for  using  subfunction  bits  are  included  in  Section 
2.3.2. 

If  a  task  invokes  a  subfunction  bit  that  is  not  supported  on  the 
system,  the  subfunction  bit  is  ignored,  but  the  QIO  request  is  not 
rejected.  For  example,  if  break-through  write  (TF.WBT)  is  not 
selected,  an  lO.WBT  or  lO.WLBlTF.WBT  function  is  interpreted  aa  an 
lO.WLB  function. 

The  following  example  is  a  QIO  request  using  more  than  one  subfunction 
bit:  a  nonechoed  (TF.RNE)  read,  terminated  by  a  special  terminator 
character  (TF.RST)  and  preceded  by  a  prompt. 

QIO$C  10. RPR  I TF.RNE I TF.RST, . . . ,<stadd , si ze , ,pradd ,prsize ,vf c> 


2.3.2   D«vic«-Sp«cif ic  QIO  Functions 

Some  device-specific  functions  described  in  this  section  are  SYSGEN 
options.  All  except  SF.GMC,  10. RPR,  SF.SMC,  lO.RTT,  and  10. GTS  can  be 
issued  by  ORing  a  particular  subfunction  bit  with  another  QIO 
function.  These  subfunction  bits  are  specified  in  the  following 
descriptions;  subfunction  bits  are  described  in  general  in  Section 
2.3.1. 

In  addition  to  the  device-specific  QIO  functions,  this  section  also 
describes  the  use  of  subfunction  bits  TF.ESQ,  TF.BIN,  and  TF.XOF. 


e 
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Subfunction  Bits  -  Summary 


I 


Equivalant 

Allowed  Subfunction 

Bits 

Function 

Subfunctlons 

TF.AST 

TF.BIN 

TF.CCO 

TF.ESO 

TF.NOT 

TF.RAL 

TF.RCU 

TF.RNE 

TF.RST 

TF.TMO 

TF.WAL 

TF.WBT 

Tf.XCC 

IF.XOF 

STANDARD  FUNCTIONS 

X 

X 

10. ATT 

lO.DET 

lO.KIL 

lO.RLB 

1 

X 

1 

X 

X 

lO.RVB 

2 

2 

2 

2 

3 

2 

lO.WLB 

t 

X 

X 

X 

I 0 . WVB 

2 

X 

X 

2 

2 

2 

X 

DEVICE-SPECIFIC  FUNCTIONS 

10. ATA 

lO.ATTITF.AST 

10. ceo 

lO.WLBITF.CCO 

3 

X 

SF.GMC 

10. GTS 

lO.RAL 

lO.RLBITF.RAL 

X 

1 

X 

X 

lO.RNE 

lO.RLBlTF.RNE 

1 

1 

X 

X 

10. RPR 

X 

1 

X 

1 

X 

X 

lO.RST 

lO.RLBITF.RST 

1 

X 

X 

X 

lO.RTT 

1 

X 

X 

X 

SF.SMC 

lO.WAL 

lO.WLBITF.WAL 

3 

3 

3 

10. WET 

lO.WLBlTF.WBT 

X 

X 

3 

1.  Exercise  great  care  when  using  Read  All  and  Read  with  Special  Terminators  together.   Obscure  problems  can  result. 

2.  These  subfunctlons  are  allowed  but  are  not  effective.   They  are  stripped  off  when  the  read  or  write  virtual  operation   is 
converted  to  a  read  or  write  logical  operation. 

3.  During   a   write-pass-all   operation   (lO.WAL  or   lO.WLBITF.WAL)   the   terminal   driver    outputs   characters   without 
interpretation;   it  does  not  keep  track  of  cursor  position. 
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2.3.2.1  10. ATA  -  10. ATA  is  a  variation  of  the  Attach  function.  The 
use  of  this  function  is  eased  by  the  /addition  of  TF.NOT  and  TF.XCC 
subfunction  bits,  described  later  in  this  section.  10. ATA  specifies 
asynt  ironous  system  traps  (ASTs)  to  process  unsolicited  input 
characters,   hfhen  called  as  follows: 

OIOSC    10. ATA, . . . ,< [AST! , {PARAMETER2) ( ,AST2) > 

NOTE 

A  minimuin  of  one  AST  parameter   (ast  or 
ast2)  is  required. 

This  function  attaches  the  terminal  and  identifies  "ast*  and  *ast2"  as 
entry  points  for  an  unsolicited-input-character  AST.  Control  passes 
to  ast  whenever  an  unsolicited  character  (other  than  CTRL/Q,  CTRL/S, 
CTRL/X,  or  CTRL/0)  is  input.  If  the  a8t2  parameter  is  specified,  an 
unsolicited  CTRL/C  character  will  result  in  entering  the  AST  specified 
in  that  parameter.  If  ast2  is  not  specified,  an  unsolicited  CTRL/C 
will  result  in  entering  the  AST  specified  in  the  ast  parameter. 

Unless  the  TF.XCC  subfunction  is  specified,  CTRL/C  is  trapped  by  the 
task  and  does  not  reach  NCR.  Thus,  any  task  that  uses  10. ATA  without 
the  TF.XCC  subfunction  should  recognize  some  input  sequence  as  a 
request  to  terminate;  otherwise,  MCR  cannot  be  invoKed  to  abort  the 
task  in  case  of  difficulty. 

Note  that  either  ast2  or  TF.XCC  can  be  used,  but  not  both  in  tho  same 
wiO  request.  If  both  are  specified  in  the  request,  an  lE.SPC  error  is 
returned. 

Upon  entry  to  the  AST  routines,  the  unsolicited  character  and 
parameter  2  are  in  the  top  word  on  the  stack,  as  shown  below.  That 
word  must  be  removed  from  the  stack  before  exiting  the  AST. 

SP+10  Event  flag  mask  word 

SP+06  PS  of  task  prior  to  AST 

SP+04  PC  of  task  prior  to  AST 

SP+02  Task's  directive  status  word 

SP-»-00  Unsolicited  character  in  low  byte;  parameter  2,  in  the 
high  byte,  is  a  user-specified  value  thit  can  be  used 
to  identify  individual  terminals  in  a  mul titerminal 
environment 

The  processing  of  unsolicited  input  ASTs  Is  eased  through  the  use  of 
TF.NOT  and  TF.XCC  subfunction  bits.  When  Tr-.XCC  is  included  in  the 
10. ATA  function,  all  characters  (except  CTRL/C)  are  handled  in  the 
manner  previously  described.  CTRL/C  marks  the  beginning  of  a  command 
line  interpreter  (CLI)  line  that  will  be  processed  by  a  CLI  task  (for 
example,  MCR);  none  of  the  characters,  including  the  CTRL/C,  are  sent 
to  the  task  issuing  the  function. 

When  unsolicited  terminal  input  (except  CTRL/C)  is  received  by  the 
full-duplex  terminal  driver  and  the  TF.NOT  subfunction  is  used,  the 
resulting  AST  serves  only  as  notification  of  unsolicited  terminal 
input;  the  terminal  driver  does  not  pass  the  character  to  the  task. 
Upon  entry  to  the  AST  service  routine,  the  high  byte  of  the  first  word 
on   the   stack   identifies  the  terminal  causing  the  AST  (parameter  2). 
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After  th«  AST  has  been  effected,  the  AST  becomes  "disarmed"  until  a 
read  request  is  issued  by  the  task.  If  multiple  characters  are 
received  before  the  read  request  is  issued,  they  are  stored  in  the 
type-ahead  buffer.  Once  the  read  request  ii  received,  the  contents  of 
the  type-ahead  buffer,  including  the  character  causing  the  AST,  is 
returned  to  the  task;  the  AST  is  then  "armed"  again  for  new 
unsolicited  input  ciiaracters.  Thus,  using  the  TF.NOT  subfunction 
allows  a  task  to  monitor  more  than  one  terminal  for  unsolicited  input 
without  the  need  to  continuously  read  each  terminal  for  possible 
unsolicited  input.  Note  that  the  TF.NOT  subfunction  cannot  be  used 
with  the  CTRL/C  AST;  an  unsolicited  CTRL/C  character  flushes  the 
type-ahead  buffer. 

See  the  RSX-llM/llM-PLOS  Executive  Reference  Manual  for  further 
details  on  ASTs. 

10. ATA  is  equivalent  to  10. ATT  ORed  with  the  subfunction  bit  TF.AST. 


2.3.2.2  lO.ATTirr.BSQ  -  The  task  issuing  this  function  attaches  a 
t«>rminal  and  notifies  the  driver  that  it  recognizes  escape  sequences 
input  from  that  terminal.  Escape  sequences  are  recognized  only  for 
solicited  input.  (See  Section  2.6  for  a  discussion  of  escape 
sequences . ) 

If  the  terminal  has  not  been  declared  capable  of  generating  escape 
sequences,  lO.ATTlTF. ESQ  has  no  effect  other  than  attaching  the 
terminal.  No  escape  sequences  are  returned  to  the  task  because  any 
ESC  sent  by  the  terminal  acts  as  a  line  terminator.  The  SF.SMC 
function  or  t'..».-  MCR  SET  /ESCSEQ  command  are  used  to  declare  the 
terminal  capable  of  generating  escape  sequences  (see  Table  2-5  and 
Section  2. 3.2.12) . 


2.3.2.3  lO.CCO  -  This  write  function  directs  the  driver  to  write  to 
the  terminal  regardless  of  a  CTRL/0  condition  that  may  be  in  effect. 
If  CTRL/0  is  in  effect,  it  is  cancelled  before  the  write  is  done. 

10. ceo  is  equivalent  to  lO.WLBlTF.CCO. 


2.3.2.4   SF.GMC  -  The  Get  Multiple   Characteristics   function   returns 
terminal  characteristics  information,  as  follows: 

0IO$C  SF.GMC, ,<stadd,size> 

St  add 

The  starting  address  of  a  data  buffer  of  length  "size"  bytes. 
Each  word  in  tho  buffer  has  the  form 

.BYTE   characteristic-name 
.BYTE   0 

character! St ic-naae 

One  of  the  bit  names  given  in  Table  2-5.  The  value  returned  in 
the  high  byte  of  each  byte-pair  is  1  if  the  characteristic  is 
true  for  the  terminal  and  0  if  it  is  not  true. 

For  the  TC.TTP  characteristic  (terminal  type),  one  of  the  values  shown 
in  Table  2-6  is  returned  in  the  high  byte. 
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Table  2-S 
Full-Dupl«x  Terminal  Driver-Terminal  Characteristics 
for  SF.GMC  and  SF.SMC  Functions 


Bit 
Naa* 

Octal 
Valu* 

Naanlng  (If  aaa«ct«d) 

Corresponding 
HCR  COMMsand 

TC.MD 

77 

Auto-baud  dataction 

SBT  /ABAUD'TTnnt 
SET  /WBAP-TTnnt 

TC,*C« 

24 

Wrap-around  moda 

TC.ANI 

122 

ANSI  CRT  tarwinal 

TC.ASPI 

76 

Raaota  Una  anawar  apaad 

IBT  /RBMOTB-TTnni apaad 

TC.AVO 

123 

VTlOO-famlly  tarainal  dlaplay 

TC.BIN 

65 

Binary  Input  MOda  (raad-paaa-all) 
no  charactara  ara  Intarpratad 
•a  control  charactara. 

SIT  /RPA-TTnni 

TC.BLK 

44 

Tarmlnal  ia  capabla  of  block 
nod*  tranafara 

TC.CTS 

72 

Suapend  output  to  terminal 

0  •  resune 

1  -  suapand 

-• 

TC.DBC 

124 

Digital  CRT  terminal 

TC . DLO  * 

41 

Dial-up  line 

SBT  /RBMOTB'TTnnt 

TC.EDT 

125 

Terminal  performa  editi    functlona 

TC.EPA 

42 

When  TC.PAR  ia  enabled: 
O'odd  parity 
I'even  parity 

-- 

TC .  ESQ 

35 

Input  escape  aequence 
recognition 

SBT  /ESCSEQ-TTnn: 

TC.PDX 

64 

Pull-duplex  mode 

SBT  /PDX-TTnn: 

TC.HPF 

17 

Hardware  form-feed  capability 
(If  0,  form-feeds  are  simulated 
using  TC.LPP.) 

SBT  /PORMPEBD-TTnn: 

TC.HFL 

13 

Number  of  fill  characters  to 

insert  after  a  carriage  return  (0-7>x) 

(Use  a  value  of  7  for  the  LA30-S.) 

SET  /HriLt>-TTnn:x 

TC.HHT 

21 

Horizontal  tab  capability  (if  0, 
horizontal  tabs  are  simulated  using 
spaces. ) 

SBT  /HHT-TTnn: 

TCHLPI 

44 

Hold  screen  mode 

SET  /HOLD"TTnn: 

TC.I8L 

6 

Subline  on  interface  (-0-15)  (Read  only) 

— 

TC.LPP 

2 

Paga  length  (1-255. -x) 

SET  /LIHES"TTnn!X 

(continued  on  next  page) 
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Table  2-5   (Cont.) 
Full-Duplex  Terminal  Driver-Terminal  Characteristics 
for  SF.GMC  and  SF.SMC  Functions 


Bit 

Nam* 

Octal 
Value 

Meaning  (If  aaacrtad) 

Corresponding 
MCR  Comaiand 

TC.NBR 

102 

Broadcaat  dlaablad 

SET  /NOBRO-TTnn: 

TC.NEC 

47 

Echo  auppraaaad 

SIT  /BCHO-TTnni 

TC.PAR 

41 

Ganarata  and  chack  parity 

— 

TC.PRI 

51 

Terminal  ia  privileged  (Read  only) 

SET  /PRlV-TTnn: 

TC . RAT 

7 

Type-ahead  buffer: 

0  ■   1-chatacter  type-ahead 

1  ■  36-charactet  type-ahead 
(RSX-llM  only) 

SET  /TYPEAHBAD-TTnn 

TC .  RGS 

126 

Terminal  auppocta  REGIS 
inatructiona 

~ 

TC.RSP2 

3 

Receiver  apeed  (bi ta-per-aecond) 

SET  /SPEED-TTnnrrcv 

xnlt 

TC.SCP 

12 

Terminal  is  a    scope  (CRT) 

SET  /CRT-TTnn: 

TC.SLV 

50 

Terminal  is  a  alave 

SET  /SLAVE-TTnn: 

TC.SMR 

25 

Upper-case  conversion  disabled 

SET  /LOWER-TTnn: 

TC.TBF 

71 

Type-ahead  buffer  count  (read), 
or  flush  (write) 

— 

TC.TBS 

100 

Type-ahead  buffer  size  (0-255-x) 
(RSX-llMPLUS  only) 

SET  /TYPEAHEAD-TTnn 

X 

TC . TBM 

101 

Type-ahead  buffer  mode 
O'tasic  typeahead 
1-CLI  typeahead 
(RSX-llM-PLUS  only) 

■" 

TC.TTP 

10 

Terminal  type  (•0-255. -x) 

SET  /X-TTnn: 
SET  /TERM-TTnn:x 

TC.VFL 

14 

Send  four  fill  characters  after 
line  feed 

SET  /VFILL-TTnn: 

TC.WID3 

1 

Page  width  (-1-255. -x) 

SET  /BOf-TTnn:x 

TC.XSp2 

4 

Transmitter  speed  (bits-per-second) 

SET  /SPEED-TTnn:rcv 

xait 

TC . BBC 

67 

Pass  eight  bits  on  input,  even 
if  not  binary  input  mode 
(TC.BIN) 

SET  /EBC-TTnn: 

I 
I 
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1.  I(f«etlv«    for   VTSa  and  VT61  only. 

2.  TC.MP,  TC.Xir,  TC.A8P  and  corraapondlnq  HCR  SET  /SPEED  and  SET  /RKHOTE 
cooMand  valu«a  for  tanalnal  r«c«lv«r  and  tranaalttar  apaada  ara  llatad  balow. 
(Tha  valid  coaiblnatlona  for  aaeh  Intoctaea  ara  In  tha  MX-llH/H-PLUS  NCR 
Op«ratlona  Manual.) 


NOT! 


Tha  NCR  SIT  /SPtIO  coaaaand  caquiraa  paraaiatara  for 
and  tranaaittar  (malt)  baud  rataa,  aa  followat 


both  racaivar   (rev) 


SET  /SPBID>TTnn:rrvsxialt 


TC.aap 

TC.MP  or 

TC.ItP      Actual  baod  rato  (In  bpa) 
valM      and  valid  NCR  IIT  /IPIH>  or  sn  /RSHOTI 
vala«s 


0 
SO 


S.7S 

8.110 

S.134 

S.150 

S.200 

S.300 

S.600 

S.1200 

S.1800 

S.2000 

S.2400 

8.3600 

8.4800 

8.7200 

8.9600 

S.BXTA  (DHll  axtarnal  apaad  A) 

8.BXTB  (DHll  axtarnal  apaad  B) 

8.19.2  19200 


(dlaablad) 

90  (Baudot  codaa  ara  not 

aupportad) 

75 

110 

134 

ISO 

200 

300 

600 

1200 

1800 

2000 

2400 

3600 

4800 

7200 

9600 


NOTE 

Spaad  can  ba  aat  only  on  DHll  and  DZll  controllara.  DSll  trananittar  and 

racaivar  apaada  nuat  ba  aqual  (no  apllt  baud  rataa  permitted).   Only  one 

value  may   be  apecifled  for  the  remote  anawar  apeed.  Thla  value  appllea 
to  both  the  tranamitter  and  receiver. 

3.  Dnaollclted  input  that  filla  the  buffer  before  a  terminator  la  received  is 
likely  invalid.  Nhen  thia  happena,  the  driver  dlacarda  the  Input  by  almulatlng 
a  CTRL/U  and  echoing  *U. 

4.  A  program  can  enable  the  auto-call  feature  of  the  DP03  modem  by  aettlng 
TC.DLU  to  a  value  of  two.  (Thia  la  in  addition  to  receiving  incoming  calla.) 
While  in  thia  mode,  read  and  write  requeata  ara  aerviced  even  when  a  line  la  not 
in  uae.  Conaaquently,  I/O  requeata  will  not  fail  when  the  line  la  hung-up, 
which  la  the  caae  for  remote  linea  (TC.DLU-1) . 
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Th«  TC.TTP  characteristic,  when  read  by  the  terminal  driver,  sets 
implicit  values  for  terminal  characteristics  TC.LPP,  TC.WID,  TC.HPF, 
TC.HHT,  TC.VPL,  and  TC.SCP  as  shown  in  Table  2-6.  These  values  can  be 
changed  (overridden)  by  subsequent  Set  Multiple  Characteristics 
requests.  In  addition,  TC.TTP  is  used  by  the  terminal  driver  to 
determine   cursor    positioning   commands,    as   appropriate. 


Table    2-6 
Bit    TC.TTP    (Terminal    Type)    Values    Set    by   SP.SMC 
and    Returned   by   SP.GMC 


iRipliclt  Chacactariatlca^ 

Octal, 

Tcrainal 

Valu*^ 

Symbolic 

Typ« 

TC.LPP 

TC.WID 

TC.Hrr 

TC . HHT 

TC.HPL 

TC.VFL 

TC.SCP 

0 

T.UNRO 

Unknown 

T.A833 

ASR33 

66 

72 

1 

T.K833 

KSR33 

66 

72 

1 

T.AS3J 

ASR3S 

72 

1 

T. 1.308 

LA30S 

80 

7 

T.L30P 

LA30P 

80 

T.LA3* 

LA36 

132 

T.VT05 

VT05 

72 

1 

1 

T.VT50 

VT50 

80 

1 

T.VT52 

VT52 

80 

T.VT55 

VT55 

80 

T.VT61 

VT61 

80 

T.L180 

LA180S 

132 

1 

T.VlOO 

VTIOO 

80 

1 

T.L120 

LA  120 

132 

1 

T.LA12 

LA  12 

132 

1 

T.LIOO 

LAIOO 

132 

1 

T.LA34 

LA34 

132 

T.LA38 

LA38 

132 

T.VIOI 

VTlOl 

80 

T.V102 

VT102 

80 

T.V105 

VT105 

80 

T.V125 

VT125 

80 

T.V131 

VT131 

80 

T.V132 

VT132 

80 

T.LA50 

LA50 

80 

1 

T.LQPl 

LQPOl 

132 

1 

T.LQP2 

LQP02 

132 

1 

1. Octal    valuaa   0-177   arc   raaatvad   by   DIGITAL, 
cuatomar    uae   to  daflna  non-DIGITAL  tariainala. 


Valuaa     200-377     ara     available     for 


2. Implicit  charactariatica  ara  ahown  aa  supported  by  the  driver.  Valuea  t>ot  shown 
ate  not  automatically  aet  by  the  driver.  An  "unknown"  terminal  ty(.*  has  no 
implicit  charactariatica. 

The  TC.CTS  characteristic  returns  the  present  suspend  (CTRL/S) ,  resume 
(CTRL/Q) ,  or  suppress  (CTRL/0)  state  set  via  the  SF.SMC  function. 
Values    returned   are  as   follows: 


Vala« 
Returned 


State 


0 
1 
2 
3 


Resume    (CTRL/Q) 

Suspend    (CTRL/S) 

Suppress    (CTRL/0) 

Both   suppress   and    suspend 
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Whan  a  value  of  0  is  ua«d  with  the  SF.Snc  function,  th«  suapcnd  stat* 
is  cleared;   a  value  of  1  selects  the  suspend  state. 

The  TC.TBF  characteristic  returns  the  number  of  unprocessed  chaiacters 
in  the  type-ahead  buffer  for  the  specif i^'1  terminal.  This  allows 
tasks  to  determine  if  any  characters  were  typed  that  did  not  require 
AST  processing.  In  addition,  the  "alue  returnad  can  be  used  to  reod 
the  exact  number  of  characters  typed,  rather  than  a  typical  value  of 
80.   or  132.   characters  for  the  terminal. 

NOTES 

1.  It  is  necessary  that  the  task  attach 
the  terminal  to  receive  characters 
from  the  type-ahead  buffer. 

2.  The  maximum  capacity  of  the 
type-ahead  buffer  is  36.  characters 
for  RSX-IIM  systems  and  255. 
characters  for  RSX-llM-PLUS  systems. 

3.  Using  TC.TBF  in  an  SF.SMC  function 
will  flush  t!ie  type-ahead  buffer. 


2.3.2.5  10. GTS  -  This  function  is  a  Get  Terminal  Support  request  that 
returns  information  to  a  4-word  buffer  specifying  which  SYSGEN-option 
features  are  part  of  the  terminal  driver.  Only  two  of  these  words  are 
currently  defined.  Table  2-7  gives  details  for  these  v/ords.  The 
10. GTS  function  is  a  SYSGEN  option.  If  10. GTS  is  issued  on  a  system 
without  10. GTS  support,  lE.IFC  is  returned  in  the  I/O  status  block. 

The  various  symbols  used  by  the  10. ^TS,  SF.GMC,  and  SF.SMC  functions 
are  defined  in  a  system  module,  TTSYM.  These  symbols  include:  Fl.xxx 
and  F2.XXX  (Table  2-7);  T.xxxx  (Table  2-6);  TC.xxx  (Table  2-5);  and 
the  SE.xxx  error  returns  described  in  Table  2-8,  Section  2.4.  These 
synbold  may  be  defined  locally  within  a  code  module  by  using: 

.MCALL    TTSYM$ 


TTSYM$ 

Symbols  that  are  not  defined  locally  are  automatically  defined  by   the 
Task  Builder. 

Octal  values  shown  for  the  symbols  are  subject  to  change.    Therefore, 
it  is  reconunended  that  only  the  symbolic  names  be  used. 
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Table  2-7 
Information  Returned  by  Get  Terminal  Support  (10. GTS)  QIO 


Octal 

Bit 

Value 

Mnerronic 

Meaning  When  Set  to  1 

Word 

0  of  Buffer: 

0 

1 

Fl.ACR 

Automatic  CR/LF  on  long  lines 

I 

2 

Fl.BTW^ 

Break-through  write 

2 

4 

Pl.BUF 

Checkpointing  during  terminal  input 

3 

10 

pi.uiaI 

Unsoliclted-input-character  AST 

4 

20 

Fl.CCO 

Cancel  CTRL/0  before  writing 

5 

40 

fi.esqI 

Recognize  escape  sequences  in  solicited 
input 

f> 

100 

Fl.HLD 

Hold-screen  mode 

7 

200 

Fl.LWCl 

Lower-  to  uppercase  conversion 

8 

40J 

Fl.RNE 

Read  with  no  echo 

9 

1000 

Fl.RPRl 

Read  after  prompting 

10 

2000 

Fl.RST 

Read  with  special  terminators 

11 

4000 

fi.rubI 

CRT  rubout 

12 

10000 

Fl.SYN 

CTRL/R  terminal  synchronization 

13 

20000 

Fl.TRW 

Read  all  and  write  all 

14 

40000 

Fl.UTB 

Input  characters  buffered  in  task's 
address  space 

15 

100000 

Fl.VBP 

Variable-length  terminal  buffers 

Word 

1  of  Bu 

ffer: 

0 

1 

F2.SCH1 

Set  characteristics  QIO  (SF.SMC) 

1 

2 

F2.GCh1 

Get  characteristics  010  (SF.GMC) 

5 

40 

F2.SFF 

Formfeed  can  be  simulated 

f, 

100 

F2.CUpl 

Cursor  positioning 

7 

200 

F2.FDX 

Full  Duplex  Terminal  Driver 

1.  SYSGEN  options  on  RSX-llM  systems, 


2.3.2.fi  lO.RAL  -  The  Read  All  function  causes  the  driver  to  pass  all 
bits  to  the  requesting  task.  The  driver  'loes  not  intercept  control 
characters  or  mask  out  the  "parity"  (high-on.er)  bit.  For  example, 
CTRL/C,  CTRL/0,  CTRL/S,  CTRL/0,  and  CTRL/Z  are  passed  to  the  program 
and  are  not  interpreted  by  the  driver. 


NOTE 

lO.RAL  echoes  the  characters  that  are 
read.  The  terminal  driver  in  Version  2 
of  RSX-llM  did  not  echo  a  Read  All.  To 
read  all  bits  without  echoing,  use 
lO.RALiTF.RNE. 


lO.RAL  is  equivalent  to  lO.RLB  ORed  with  the  subfunction  bit  TF.RAL. 
The  lO.RAL  function  can  be  terminated  only  by  a  full  character  count 
(input  buffer  full)  . 
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2.3.2.7  lO.RNB  -  The  lO.RNE  function  reads  terminal  Input  characters 
without  echoing  the  characters  back  to  the  terminal  for  Immediate 
display.  This  feature  can  be  used  when  typing  sensitive  information 
(for  example,  a  password  or  combination)  or  when  reading  a  badge  with 
the  RT02-C  terminal. 

(Note  that  the  no-echo  mode  can  also  be  selected  with  the  SF.SMC 
function;   see  Table  2-5,  bit  TC.NEC.) 

CTRL/R  Is  Ignored  while  an  lO.RNE  Is  in  progress. 

The  lO.RNE  function  Is  equivalent  to  lO.RLB  ORed  with  the  subfunctlon 
bit  TF.RNE. 


2.3.2.8  10. RPR  -  The  10. RPR  Read  After  Prompt  functions  as  an  lO.WLB 
(to  write  a  prompt  to  the  terminal)  followed  by  lO.RLB.  However, 
TO. RPR  differs  from  this  combination  of  functions  as  follows: 

e  System  overhead  is  lower  with  the  10. RPR  because  only  one  QIC 
is  processed. 

•  When  using  the  10. RPR  function,  there  is  no  "window"  -during 
which  a  response  to  the  prompt  may  be  ignored.  Such  a  window 
occurs  if  IO.WAL/IO.R1.B  Is  used,  because  no  read  may  be  posted 
at  tho  time  the  response  is  received. 

•  If  the  issuing  task  is  checkpointable,  it  can  be  checkpolnted 
during  both  the  prompt  and  the  read  requested  by  the  10. RPR. 

•  A  CTRL/0  that  may  be  in  effect  prior  to  issuing  the  10. RPR  is 
canceled  before  the  prompt  is  written. 

Subfunctlon  bits  may  be  ORed  with  10. RPR  to  write  the   prompt  as      a 

Write   All   (TF.BIN)   and   to   send   XOFF  after  the  read  (TF.XOF).   In 

addition,  read  subfunctlon  bits  TF.RAL,  TF.RNE,  and  TF.RST  can  be  used 
with  10. RPR. 


NOTE 

If  an  10. RPR  function  is  in  progress 
when  the  driver  receives  a  CTRL/R  or 
CTRL/U,  the  prompt  is  redisplayed. 


2.3.2.9  I0.RPRlTE.BIN  -  This  function  results  in  a  read  after  a 
"binary"  prompt;  that  is,  a  prompt  Is  written  by  the  driver  with  no 
character  interpretation  (as  if  it  were  issued  as  an  lO.WAL) . 


2.3.2.10  lO.RPRITE.XOF  -  This  function  causes  the  driver  to  send  an 
XOFF  to  the  terminal  after  its  prompt-and-read.  The  XOFF  or  CTRL/S 
may  have  the  effect  of  inhibiting  input  from  the  terminal,  if  the 
terminal  recognizes  XOFF  for  this  purpose.  TF.XOF  is  ignored  when 
full-duplex  I/O  is  in  use. 
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2.3.2.11  I0.R8T  -  This  function  is  similar  to  an  lO.RLB,  except 
certain  special  characters  terminate  the  read.  These  characters  are 
In  the  ranges  0-037  and  175-177.  The  driver  does  not  interpret  the 
terminating  character,  with  certain  exceptions.!  For  example,  a 
horizontal  TAB  (Oil)  is  not  expanded,  a  RUBOUT  (or  DKL,  177)  does  not 
erase,  and  a  CTRL/C  does  not  produce  an  MCR  prompt. 

Upon  successful  completion  of  an  lO.RST  request  that  was  not 
terminated  by  filling  the  input  buffer,  the  first  word  of  the  I/O 
status  block  contains  the  terminating  character  in  the  high  byte  and 
the  IS. sue  status  code  in  the  low  byte.  The  second  word  contains  the 
number  of  bytes  contained  in  a  buffer.  The  terminating  character  Is 
not  put  In  the  buffer. 

lO.RST  is  equivalent  to  lO.RLBl TF.RST. 


2.3.2.12  SP.SMC  -  This  function  enables  a  task  to  set  and  reset  the 
characteristics  of  a  terminal.  Set  Multiple  Characteristics  is  the 
inverse  function  of  SF.GMC.  Like  SF.GMC,  it  is  called  in  the 
following  way: 

0IO$C  SF.SMC, . . . ,<stadd,slze> 

stadd 

The  starting  address  of  a  buffer  of  length   "size"   bytes.    Each 
word  in  the  buffer  has  the  form 

.BYTE  characteristic-name 
.BYTE  value 

characteristic-name 

One  of  the  symbolic  bit  names  given  In  Table  2-5. 

value 

Either  0  (to  clear   a   given   characteristic)   or   1   (to   set   a 
characteristic)  . 

Table  2-5  notes  the  restrictions  that  apply  to  these  characteristics. 

If  the  characteristic-name  Is  TC.TTP  (terminal  type),  value  can  have 
any  of  the  values  lijted  in  Table  2-fi. 

A  nonprivi leged  task  can  only  issue  an  SF.SMC  request  for  its  own 
terminal  (TI:).   A  privileged  task  can  Issue  SF.SMC  to  any  terminal. 

Terminal  output  can  be  suspended  or  resumed  (simulated  CTRL/S  and 
CTRL/0,  respectively)  by  specifying  an  appropriate  value  for  TC.CTS. 
A  value  of  0  resumes  output  and  a  value  of  1  suspends  output. 


1.  If  upper-  to  lowercase  conversion  Is  disabled,  characters  175  and 
176  do  not  act  as  terminators.  CTRL/0,  CTRL/Q,  and  CTRL/S  (017,  021, 
and  023,  respectively)  are  not  special  terminators.  The  driver 
interpretc  them  as  output  control  characters  In  a  normal  manner. 
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Specifying  any  value  for  TC.TBF  flushes  (clears)  the  type-ahead  buffer 
(forces  the  type-ahead  buffer  count  to  0). 


2.3.2.13  lO.RTT  -  This  QIO  function  reads  characters  in  a  manner  like 
the  lO.RLB  function,  except  a  user-specified  character  terminates  the 
read  operation.  The  specified  character's  code  can  range  from  0-377. 
It  is  user  designated  by  setting  the  appropriate  bit  in  a  Ifi-word 
table  that  corresponds  to  the  desired  character.  Multiple  characters 
can  be  specified  by  setting  their  corresponding  bits. 

The  16-\i/ard  table  starts  at  the  address  specified  by  the  table 
parameter.  The  first  word  contains  bits  that  represent  the  first  ]6 
ASCII  character  codes  (0-17);  similarly,  the  second  word  contains 
bits  that  represent  the  next  Ifi  character  codes  (20-37),  and  so  forth, 
through  the  sixteenth  word,  bit  15,  which  represents  character  code 
377.  For  example,  to  specify  the  %  symbol  (code  045)  as  a  read 
terminator  character,  set  bit  05  in  the  third  word,  sJice  the  third 
word  of  the  table  contains  bits  representing  character  codes  40-57^ 

If  the  CTRL/S  (023),  CTRL/0  (021),  and/or  any  characters  whose  codes 
are  greater  than  177  is/are  desired  as  the  terminator  character (s) , 
the  terminal  must  be  set  to  read-pass-all  operation  (TC.BIN^l),  or 
read-pass  8-bits  (TC.8BC),  as  listed  in  Table  2-5. 

The  optional  time-out  count  parameter  can  be  included,  as  desired. 


2.3.2.14  lO.WAL  -  The  Write  All  function  causes  the  driver  to  pass 
all  output  from  the  buffer  without  interpretation.  It  does  not 
intercept  control  characters.  Long  lines  are  not  wrapped  around  if 
input/output  wrap-around  has  been  selected. 

lO.WAL  is  equivalent  to  the  lO.WLB! TF.WAL  function. 


2.3.2.15  lO.WBT  -  The  IO.V"T  function  Instructs  the  driver  to  write 
the  buffer  regardless  of  the  I/O  status  of  the  receiving  terminal.  If 
an  TO.WBT  function  is  issued  on  a  system  that  does  not  support  lO.WBT, 
it  is  treated  as  an  lO.WLB  function. 

•  If  another  write  function  is  currently  in  progress,  it 
finishes  the  current  request  and  the  lO.WBT  is  the  next  write 
Issued.  The  effect  of  this  is  that  a  CTRL/S  can  stop  lO.WBT 
functions.  Therefore,  it  may  be  desirable  for  tasks  to  time 
out  on  lO.WBT  operations. 

•  If  a  read  is  currently  posted,  the  lO.WBT  proceeds,  and  an 
automatic  CTRL/R  is  performed  to  redisplay  any  input  that  was 
received  before  the  break-through  write  was  effected  (if  the 
terminal  is  not  in  the  full-duplex  mode). 

•  CTRL/0,  if  in  effect,  is  canceled. 

e   An  escape  sequence  that  was  interrupted  is  rubbed  out. 

An  lO.WBT  function  cannot  break  through  anotier  lO.WBT  that  Is  in 
progress. 

Break-through  write  may  only  be  issued  by  a  privileged  task.  The 
privileged  MCR  command  BRO  (broadcast)  uses  lO.WBT. 
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2.3.2.16   lO.HNG  -  The  lO.HNG  function  disconnects  a  terminal  that 
on  a  remote  line.   This  function  has  no  arguments. 


is 


A  nonpr Ivl leged  task  can  only  issue  an   lO.HNG   request   for   its  own 
terminal  (TI:).   A  privileged  task  can  Issue  lO.HNG  to  any  terminal. 


2.4   STATUS  RETURNS 

Table  2-8  lists  error  and  status  conditions  that  are  returned   by 
terminal  driver  to  the  I/O  status  block. 


the 


Moat  RSX-llM  error  and  status  codes  returned  are  byte  values.  For 
example,  the  value  for  IS.SUC  is  1.  However,  IS.CC,  IS.CR,  IS. ESC, 
and  IS. ESQ  are  word  values.  When  any  of  these  codes  are  returned,  the 
low  byte  indicates  successful  completion,  and  the  high  byte  shows  what 
type  of  completion  occurred. 

To  test  for  one  of  these  word-value  return  codes,  first  test  the  low 
byte  of  the  first  word  of  the  I/O  status  block  for  the  value  IS.SUC. 
Then,  test  the  full  word  for  IS.CC,  IS.CR,  IS. ESC,  or  IS. ESQ.  (If  the 
full  word  tests  equal  to  IS.SUC,  then  itr  high  byte  is  0,  indicating 
byte-count  termination  of  the  read.) 

The  "error"  return  IE. EOF  may  be  considered  a  successful  read  since 
characters  returned  to  the  task's  buffer  can  be  terminated  by  a  CTRL/Z 
character . 

The  SE.xxx  codes  are  returned  by  the  SF.GMC  and  SF.SMC  functions  as 
described  in  Sections  2.3.2.4  and  2.3.2.12.  When  any  of  these  codes 
are  returned,  the  low  byte  in  the  first  word  in  the  I/O  status  block 
will  contain  IE. ABO.  The  second  lOSB  word  contains  an  offset 
(starting  from  0)  to  the  byte  In  error  in  the  QIO's  stadd  buffer. 


Table  2-8 
Terminal  Status  Returns 


Code 

Reason 

IE. EOF 

Successful  completion  on  a  read  with  end-of-file 

The   line   of   input   read   from   the   terminal    was 

terminated   with   the   end-of-file  character  CTRL/Z. 

The  second  word  of  the  I/O  status  block  contains   the 

number   of   bytes   read   before  CTRL/Z  was  seen.   The 

input  buffer  contains  those  bytes. 

IS.SUC 

Successful  completion 

The  operation  specified   in   the   QIO  directive   was 

- 

completed   successfully.    If   the  operation  involved 

reading  or  writing,  you  can  examine  the   second   word 

of   the   I/O   status  block  to  determine  the  number  of 

bytes  processed.   The   input   buffer   contains   those 

bytes. 

(continued  on  next  page) 
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Table  2-8   (Cont.) 
Terminal  Status  Returns 


Coda 


Reason 


IS.CC        Successful  completion  on  a  read 

The  line  of  input  read  from  the  terminal  was 
terminated  by  a  CTRL/C.  The  input  buffer  contains 
the  bytes  read. 

IS.CR        Successful  completion  on  a  read 

The  line  of  input  re/«d  from  the  terminal  was 
terminated  by  a  carriage  return.  The  input  buffer 
contains  the  bytes  read. 

IS. ESC       Successful  completion  on  a  read 

The  line  of  input  read  from  the  terminal  was 
terminated  by  an  Altmode  character.  The  input  buffer 
contains  the  bytes  read. 

IS. ESQ       Successful  completion  on  a  read 

The  line  of  input  read  from  the  terminal  was 
terminated  by  an  escape  sequence.  The  input  buffer 
contains  the  bytes  read  and  the  escape  sequence. 

IS.PND       I/O  request  pending 

The  operation  specified  in  the  QIO  directive  has  not 
yet  been  executed.  The  I/O  status  block  is  filled 
with  Os. 

IS.TMO       Successful  completion  on  a  read 

The  line  of  input  read  from  the  terminal  was 
terminated  by  a  time-out  (TF.TMO  was  set  and  the 
specified  cime  interval  was  exceeded).  The  input 
buffer  contains  the  bytes  read. 

IE. ABO       Operation  aborted 

The  specified  I/O  operation  was  cancelled  by  lO.KIL 
while  in  progress  or  while  in  the  I/O  queue.  The 
second  word  of  the  I/O  status  block  indicates  the 
number  of  bytes  that  were  put  in  the  buffe:"  before 
the  kill  was  effected. 

IF. BAD       Bad  parameter 

The  size  of  the  buffer  exceeds  8128  bytes. 

lE.BCC       Framing  error 

A  framing  error  was  hardware-detected  and  returned  by 
the  controller.  All  characters  up  to  (but  not 
including)  the  erroneous  character  are  in  the  buffer. 
This  condition  can  result  by  pressing  the  BREAK  key 
on  some  terminals,  or  by  hardware  problems. 

(continued  on  next  page) 
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Table  2-8   (Cont.) 
Terminal  Status  Returns 


Code 


I E . DAA 


lE.DAO 


I E . DNA 


lE.DNR 


lE.IES 


IE. IPC 


Reason 


Device  already  attached 

The  physical  device  unit  specified  In  .in  10. ATT 
function  was  already  attached  by  the  issuing  task. 
This  code  indicates  that  the  issuing  task  has  already 
attached  the  desired  physical  device  unit,  not  that 
the  unit  was  attached  by  another  task.  If  v'-he  attach 
jpecified  TF.AST  or  TF.ESO»  these  subfunction  bits 
have  no  effect. 

Data  overrun  error 

A  data  overrjn  error  was  hardware-detected  and 
returned  by  the  controller.  All  characters  up  to 
(but  not  including)  the  erroneous  character  are  in 
the  buffer.  This  error  occurs  when  a  hardware 
failure  or  incompatibility  causes  characters  to  be 
received  by  the  controller  faster  than  they  can  be 
processed  (that  is,  an  incorrect  serial  I/O  baud  rate 
or  format  exists) . 


specified  in  an  ^O.DET 
by  the  issuing  task.  This 
attachment  status  of  other 


Device  not  attached 

The  physical  device  unit 
function  was  not  attached 
code  has  no  bearing  on  the 
tasks . 

Device  not  ready 

The  physical  device  unit  specified  in  the  QIO 
directive  was  not  ready  to  perform  the  desired  I/O 
operation.  This  code  is  returned  to  indicate  one  of 
the  following  conditions: 

•  A  time-out  occurred  on  the   physical   device   unit 
(that  is,  an  interrupt  was  lost). 

•  An  attempt  was  made  to  perform  a   function  on  a 
remote  DHll  or  DZll  line  without  carrier  present. 

Invalid  escape  sequence 

An  escape  sequence  was  started  but  escape-sequence 
syntax  was  violated  before  the  sequence  was 
completed.  (See  Section  2.6.4.)  The  character 
causing  the  violation  is  the  last  character  in  the 
buffer. 

Illegal  function 

A  function  code  specified  in  an  I/O  request  was 
illegal  for  terminals;  or,  the  function  code 
specified  was  a  SYSGEN  option  not  selected  for  this 
system. 


(continued  on  next  page) 
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Table  2-8   (Cont.) 
Terminal  Status  Returns 


Code 


Re^.don 


IE. NOD 


Buffer  allocation  'allure 


lE.OFL 


IE. PES 


System  dynamic  storage  has  been  depleted  resulting  in 
insufficient  space  available  to  ullocate  an 
intermediate  buffer  for  an  input  request  or  an  AST 
block  for  an  attach  requost. 

Device  off  line 

The  physical  device  unit  associated  with  the  LUN 
specified  in  the  QIO  directive  was  not  on  line.  When 
the  system  was  booted,  a  device  check  indicated  that 
this  physical  device  unit  was  not  in  the 
configuration.  In  RSX-llM-PLUS  systems,  the  physical 
device  unit  could  have  been  configured  off  line. 

Partial  escape  sequence 

An  escape  sequence  ■'as  started,  but  read-buffer  space 
was  exhausted  before  the  sequence  was  completed.  See 
Section  2.6.4.3. 


lE.PRI 


lE.SPC 


lE.VER 


SE.NIH 


SE.FIX 


SE.VAL 


Privilege  violation 

In  a  multiuser  system,  a  nonpir ivileged  task  issued  an 
lO.WBT,  directed  an  SF.SMC  to  a  terminal  other  than 
TI:,  or  it  attempted  to  set  its  privilege  bit. 

Illegal  address  space 

The  buffer  specified  for  a  read  or  write  request  was 
partially  or  totally  outside  the  address  space  of  the 
issi>ing  task,  a  byte  count  of  0  was  specified,  or  an 
odd  or  0  nST  address  was  specified. 

Character  parity  error 

A  parity  error  was  hardware-detected  and  returned  by 
the  controller.  All  characters  up  to  (but  not 
including)  the  erroneous  character  are  in  the  buffer. 

A  terminal  characteristic  other  than  those  in  Table 
2-5  was  named  in  an  SF.GMC  or  SF.SMC  request,  or  a 
task  attempted  to  assert  TC.PRI. 

An  attempt  was  made  to  change  a  fixed  characteristic 
in  a  SF.SMC  subfunction  requsst  (for  example,  an 
attempt  was  made  to  change  the  unit  number) . 

The  new  value  specified  in  an  SF.SMC  request  for  the 
TC.TTP  terminal  characteristic  was  not  one  of  those 
listed  in  Table  2-6. 


(continued  on  next  page) 
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Table  2-8   (Cont.) 
Terminal  Status  Returns 


Code 


Reason 


SE.NSC 


SE.SPD 


An  attempt  was  made  to  change  a  nonsettable 
characteristic.  This  error  can  occur  when  an  attempt 
is  made  to  make  a  local-only  line  a  remote  line  when 
the  controller  does  not  support  remote  lines,  or  when 
no  remote  line  support  was  specified  durfng  SYSGEN. 

The  new  speed  specified  in  an  SF.SMC  subfunction 
request  was  not  valid  for  the  controller  associated 
with  the  specified  terminal. 


2.5   CONTROL  CHARACTERS  AND  SPECIAL  KEYS 

This  section  describes  the  mijanings  of  special  terminal  control 
characters  and  keys  for  RSX-llM.  Note  that  the  driver  does  not 
recognize  control  characters  and  special  keys  during  a  Read  All 
request  (lO.RAL),  and  recognizes  only  some  of  them  during  a  Read  with 
Special  Terminators  (lO.RST). 


2.5.1   Control  Characters 

A  control  character  is  input  from  a  terminal  by  holding  the  control 
key  (CTRL)  down  while  typing  one  other  key.  Three  of  the  control 
characters  described  in  Table  2-9,  CTRL/R,  CTRL/U,  and  CTRL/Z,  are 
echoed  on  the  terminal  as  "R,  "U,  and  "Z,  respectively. 


Table  2-9 
Terminal  Control  Characters 


Character 

Meaning 

CTRL/C 

Typinq   CTRL/C   causes   unsolicitea   input   on    that 

terminal  to  be  directed  to  a  control  line  interpreter 

task,  such  as  MCR.   (Command   line   interpreters   are 

invoked   and   display  a  prompt  in  a  manner  similar  to 

that  of  MCR;   therefore,  for   the   purposes   of   this 

discussion,   it   is   assumed   that  MCR  is  the  command 

line  interpret>2r  in  use,  although  the  terminal  driver 

will   respond  to  other  command  line  interpreters  in  a 

sim.'lar  manner.)  The  "MCR>"  prompt  is  echoed  when  the 

ter^iinal  driver  is  ready  to  accept  an  unsolicited  MCR 

command  line  for  input.   When  the   r  solicited   input 

is  terminated,  the  command  line  is  -,  .jsed  to  MCR. 

If  the  last  character  typed  on   the   terminal   was  a 

CTRL/S   (suspend   output) ,   CTRL/C  restarts  suspended 

output  and  directs  subsequent  input  tc  MCR. 

If   the  hold-screen  mode   SYSGCN  option  has  been 

selected   and   the   terminal   is   a   VT5x   or  VT61  in 

hold-screen   mode,   typing   a   CTRL/C    removes    the 

terminal  from  tiold-screen  mode. 

(continued  on  next  page) 


2-27 


FULL-DUPLEX  TERMINAL  DRIVER 


Table  2-9   (Cont.) 
Terminal  Control  Characters 


r 


haracter 


Meaning 


CTRL/I 

CTRL/ J 
CTRL/K 

CTRL/L 


CTRL/M 
CTRL/0 


CTRL/Q 


CTRL/C  characters  can  also  be  directed  to  a  task  if 
the  task  has  attached  a  terminal  and  has  specified  an 
unsolicited-input-character  AST  (sje  Section 
2.3.2.1).  CTRL/C  charact'>rs  are  also  passed  to  a 
task  if  an  lO.R^'L  or  lO.RST  function  is  effected. 


NOTE 

If  the  terminal  driver  receives  a  CTRL/C 
character  during  a  read  operation  (except 
during  a  Read-Pass-All  operation  or  a  Read 
With  Special  Terminators  operation),  the  read 
operation  is  terminated,  the  cype-ahead 
buffer  is  cleared,  and  an  IS.CC  status  code 
is  returned  to  the  task. 


CTRL/I  or  TAB  characters  initiate  a  horizontal  tab, 
and  the  terminal  spaces  to  the  next  tab  stop.  Tabs 
at  every  eighth  character  position  are  simulated  by 
the  terminal  driver. 

CTRL/J  is  equivalent  to  a  LINE  FEED  character. 

CTRL/K  Initiates  a  vertical  tab,  and  the  terminal 
tabs  to  the  next  vertical  tab  stop.  For  a  CRT 
terminal,  four  LINE  FEEDs  are  output. 

CTRL/L  initiates  a  formfeed.  If  tho  terminal  has 
hardware  formfeed  support,  the  driver  echos  "L. 
Otherwise,  the  driver  simulates  the  formfeed  by 
outputtlng  enough  LINE  FEED  characters  to  advance  the 
next  character  position  to  the  top  of  the  next  page. 
If  a  CRT  terminal  is  in  use,  four  LINE  FEEDs  are 
output . 

CTRL/M  is  equivalent  to  a  carriage  RETURN  character 
(see  Section  2.5.2) . 

CTRL/0  suppresses  terminal  output.  For  attached 
terminals,  CTRL/0  remains  In  effect  (output  is 
suppressed)  until  one  of  the  following  occurs: 

•  The  terminal  is  detached. 

•  Another  CTRL/0  character  is  typed. 

•  An  10. ceo  or  lO.WBT  function  is  issued. 

•  Input  is  entered. 

For  unattached  terminals,  CTRL/O  suppresses  output 
for  only  the  current  output  buffer  (typically  one 
line)  . 

CTRL/Q  resumes  terminal  output  previously  suspended 
by  means  of  CTRL/S. 


(continued  on  next  page) 
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Table  2-9   (Cont.) 
Terminal  Control  Characters 


Character 


CTRL/S 
CTRL/R 


CTRL/U 

CTRL/X 
CTRL/Z 


Meaning 


CTRL/S  suspends   terminal   output, 
resumed  by  typing  CTRL/Q  or  CTRL/C, 


(Output   can   be 
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Typing  CTHL/U  before  typing  a  line  terminator  deletes 
previously  typed  characters  back  to  the  beginning  of 
the  line.  The  system  echoes  this  character  as  "U 
followed  by  a  carriage  return  and  a  line  feed. 

This  character  clears  the  type-ahead  buffer. 

CTRL/Z  indicates  an  end-of-file  for  the  currenL 
terminal  input.  It  signals  MAC,  PIP,  TKB,  and  other 
system  tasks  that  terminal  input  is  complete, 
allowing  the  task  to  exit.  The  system  echoes  this 
character  as  "Z,  followed  by  a  carriage  return  and  a 
line  feed. 


2.5.2  Special  Keys 

The  Escape,  carriage  RETURN,  and  RUBOUT  keys  have  special  significance 
for  terminal  input,  as  described  in  Table  2-10.  A  line  can  be 
terminated  by  an  ESCape  (or  Altmode) ,  carriage  RETURN,  or  CTRL/Z 
characters,  or  by  completely  filling  the  input  buffer  (that  is,  by 
exhausting  the  byte  count  before  a  line  terminator  is  typed).  The 
standard  buffer  size  for  a  terminal  can  be  determined  for  a  task  by 
issuing  a  Get  LUN  Information  system  directive  and  examining  Word  5  of 
the  buffer.  An  operator  can  obtain  the  same  information  with  the  MCR 
SET  /BUF=TI:   command. 


2.fi   ESCAPE  SEQUENCES 

Escape  sequences  are  strings  of  two  or  more  characters  beginning  with 
an  ESC  (033)  character.  In  RSX-llM  systems,  escape  sequence  support 
described  in  this  section  is  a  SYSGEN  option.  Some  terminals  generate 
an  escape  sequence  when  a  special  key  is  pressed  (for  example,  the  FCN 
key  on  the  VTfil).  On  any  terminal,  an  escape  sequence  may  be 
generated  manually  by  typing  ESCape  followed  by  the  appropriate 
characters. 


2-29 


FULL-DUPLEX  TERMINAL  DRIVER 


Escape  sequences  provide  a  way  to  pass  input  to  a  task  without 
interpretation  by  the  operating  system.  This  could  be  done  with  a 
number  1-character  Read  All  functions,  but  escape  sequences  allow  them 
to  be  read  with  lO.RLB  requests. 


Key 


Escape 


RETURN 


RUBOUT 


Table  2-10 
Special  Terminal  Keys 


Meaning 


If  escape  sequences  are  not  recognized,  typing  ESCape 
or  Altmode  signals  the  terminal  driver  that  there  is 
no  further  Input  on  the  current  line.  This  line 
terminator  allows  further  input  on  the  same  line, 
because  the  carriage  or  cursor  is  not  returned  to  the 
first  column  position. 

If  escape  sequences  are  recognized,  ESCape  signals 
the  beginning  of  an  escape  sequence.  (See  Section 
2.f>.) 

Typing  RETURN  terminates  the  current  line  and  causes 
tb"  carriage  or  cursor  to  return  to  the  first  column 
on  the  line. 

Typing  RUBO"T  deletes  the  last  character  typed  on  an 
input-  line.  Only  characters  typed  since  the  last 
line  terminator  may  be  deleted.  Sc.eLV.3  characters 
can  be  deleted  in  sequence  by  *'yrin'3  successive 
RUBOUTs. 
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typing  CBA: 


ABC\CBA\CBA 


The  second  backslash  is  not  displayed  if  a  line 
terminator  Is  typed  after  rubbing  out  the  characters 
on  a  line,  as  in  the  following  example: 

Aac\CBA 

At  SYSGEN  time,  the  "CRT  rubout"  feature  can  be 
selected.  This  feature  applies  to  a  terminal  only 
after  a  SET  MCR  directive  has  been  issued: 

SET  /CRV=TI: 


(continued  on  next  page) 
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Table  2-10   (Cont.) 
Special  Terminal  Keys 


Key 

Meaning 

If  the  CRT  rubout  feature  was  selected,  RUBOUT  causes 

the   last  typed  character  (if  any)  to  be  removed  from 

the     incomplete     input     line      and      a 

backspace-space-backspace   sequence  of  characters  for 

that   terminal   are   echoed.    If   the    last    typed 

character   was  a  tab,  er.ough  backspaces  are  issued  to 

move  the  cursor  to  the  character  position  before   the 

tab  was   typed.    If  a  long  input  line  was  split,  or 

"wrapped,"  by  the   automatic-carr i.ige-return  option. 

ond   a  RUBOUT  erases  the  last  charctcter  of  a  previous 

line,  the  cursor  is  not  moved  to  the   previous   line. 

CTRL/R  must   be   used   to   resynchroni ze  the  current. 

display  with  the  contents  of   the   incomplete   input 

line. 

2.fi.l   Definition 

The  format  of  an  escape  sequence  as  defined   in  American   National 
Standard  X  3.41—  1974  and  used  in  the  VTIOO  is: 

ESC   ...   F 


ESC 


The  introducer  control  character  (33(8))  that  is  named  escape. 


The  intermediate  bit  combinations  that  may  or  may  not  be 
present.  I  characters  are  bit  combination  40(8)  to  57(8) 
inclusive  in  both  7-  and  8-bit  environments. 


The  final  character.  F  characters  are  bit  combinations  60(8) 
to  176(8)  inclusive  in  escape  sequences  in  both  7-  and  8-bit 
environments. 


The  occurrence  of  characters  in  the  inclusive  ranges  0(8)  to  37(8) 
is  tec'inically  an  error  condition  whose  recovery  is  to  execute 
immediately  the  function  specified  by  the  character  and  then 
continue  with  the  escape  sequence  execution.  The  exceptions  ar?: 
if  the  character  ESC  occurs,  the  current  escape  sequence  is  aborted, 
and  a  new  one  commences,  beginning  with  the  ESC  just  received;  if 
the  character  CAN  (30(8))  or  the  character  SUB  (32(8))  occurs,  the 
current  escape  sequence  is  aborted,  as  is  the  case  with  any  control 
character . 


There  are   five  exceptions   to   thi  •   general   definition; 
exceptions  are  discussed  in  Section  2.6.5. 


these 
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2.6.2   Prerequisites 

Two  prerequisites  must  be  satisfied  before  escape  sequences  can  be 
received  by  a  task. 

First,  the  task  must  "ask"  for  them  rty  issuing   an   10. ATT  function 
and  invoking  the  subfunction  bit  TF.FSQ, 

Second,  the  terminal  must  be  declared  capable  of  generating   escape 
sequences.   This  may  be  done  with  an  MCR  SET  command: 

SET  /ESCSE?»TI: 

An  alternative  way  to  tell  the  driver  that  the  terminal  can  generate 
escape  sequences  is  by  issuing  the  Set  Multiple  Characteristics 
request.   (See  Section  2.3.2.12). 

If  either  of  these  prerequisites  is  not  satisfied,  the  ESC  character 
is  treated  as  a  line  terminator. 

If  both  prerequisites  are  satisfied,  ttrl/SHIFT/l.  (037)  may  be  used  as 
an  Altmode  character.!  This  character  does  not  act  as  an  Altmode  from 
a  terminal  that  cannot  generate  escape  sequences. 


2.6.3   Characteristics 

Escape  sequences  always  act  as  line  terminators.  That  is,  an  input 
buffer  may  contain  other  characters  that  are  not  part  of  an  escape 
sequence,  but  an  escape  sequence  always  comprises  the  last  characters 
in  the  buffer. 

Escape  sequences  are  not  echoed.  However,  if  a  non-CRT  rubout 
sequence  is  in  progress,  it  is  closed  with  a  backslash  when  an  escape 
sequence  is  begun. 

Escape  sequences  are  not  recognized  in  unsolicited  input  streams. 
Neither  are  they  recognized  in  a  Read  with  Special  Terminators 
(subfunction  bit  TF.RST)  nor  in  a  Read  All  (subfunction  bit  TF.RAL). 


2.6.4   Escape  Sequence  Syntax  Violations 

A  violation  of  the  ay. tax  defined  in  Section  2.6.1  causes   the  driver 
to  abandon  the  escape  sequence  and  to  return  an  error  (lE.IES). 


2.6.4.1  DEL  or  RUBOUT  (177)  -  The  character  DEL  or  RUBOUT  is  not 
legal  within  an  escape  sequence.  Typing  it  at  any  point  within  an 
escape  sequence  causes  the  entire  sequence  to  be  abandoned  and  deleted 
from  the  input  buffer.  Thus,  use  DEL  or  RUBOUT  to  abandon  an  escape 
sequence,  if  desired,  once  you  have  begun  it. 


1.  An  Altmode  is  a  line  terminator  that  does  not  cause  the  cursor  to 
advance  to  a  new  line.  On  terminals  that  cannot  generate  escape 
sequences,  the  ESCape  key  acts  as  an  Altmode.  Characters  175  and  176 
also  function  as  Altmodes  if  the  terminal  has  not  been  declared 
lowercase  (MCR  command  SET  /LOWER) . 
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2.f>.4.2  Control  Characters  (0-037)  -  The  reception  of  any  character 
in  the  range  0  to  037  (with  four  exceptions  —  see  footnote^)  is  a 
syntax  violation  that  terminates  the  read  with  an  error  (lE.IES). 


2.6.4.3   Full  Buffer  -  A  syntax  error  results  when  an  escape   sequence 
is   terminated   by   running  out   of  read-buffer  space,  rather  than  by 

receipt  of  a  final  character.   The   error   IE. PES   is  returned.    For 

example,   after  a  task  issues  an  lO.RLB  with  a  buffer  length  of  2,  and 
you  type: 

ESC  !   A 

the  buffer  contains  "ESC  !",  and  the  I/O  status  block  contains: 


lOSB 


IE. PES 


The  "A"  is  treated  as  unsolicited  input. 


2.6.5   Exceptions  to  Escape-Sequence  Syntax 

Five  "final  characters"  that  normally  terminate  an  escape  sequence  are 
treated  as  special  cases  by  the  terminal  drivsr  for  use  with  certain 
terminals: 


ESC 

?.  .  . 

ESC 

0..  . 

ESC 

p.. . 

ESC 

Y.  .  . 

ESC 

[... 

Refer  to  documentation  supplied  with  the  specific  terminal (s) 
for  correct  use  of  escape  sequences. 


in   use 


2.7   VERTICAL  FORMAT  CONTROL 

Table  2-11  is  a  summary  of  all  characters  used  for  vertical  format 
control  on  the  terminal.  Any  one  of  these  characters  can  be  specified 
as  the  value  of  the  vfc  parameter  in  lO.WLB,  lO.WVB,  lO.WBT,  lO.CCO, 
or  10. RPR  functions. 


1.  Four  control  characters  are  allowed:  CTRL/Q,  CTRL/S,  CTRL/X,  and 
CTRL/0.  These  characters  are  handled  normally  by  the  operating  system 
even  when  an  escape  sequence  is  in  progress.   For  example,  entering: 


ESC  CTRL/S  A 


gives: 


lOSB 


IS. ESQ 


with  the  additional  effect  of  turning  off  the  output  stream. 
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2.8   AUTOMATIC  CARRIAGE  RETURN 

Individual  terminals  can  be  set  for  wrap-around,  as  desired,  using  the 
MCR  SET  command 

>SET  /WRAP=TTxx: 

Once  wrap-around  has  been  selected,  the  column   at   which   wrap-around 
occurs  can  be  selected  using  the  MCR  SET  command 

:.  >SET  /BUF=TI:n 
.,  ;  > 

The  SET  /BUF  command  can  also  be  used  without  an  argument   to   display 
the  current  buffer  width  for  a  terminal; 

>SET  /BUF=TI: 
BUF=TI: 00072. 
> 


•    Table  ^-11 
Vertical  Format  Control  Characters 


Octal 
Value 


Character 


Meaning 


040 


060 


blank 


061 


053 


044 


000 


null 


SINGLE  SPACE  -  Output  one  line  feed,  print  the 
contents  of  the  buffer,  and  output  a  carriage 
return.  Normally,  printing  immediately  follows 
the  previously  printed  line. 

DOUBLE  SPACE  -  Output  two  line  feeds,  print  the 
contents  of  the  buffer,  and  output  a  carriage 
return.  Normally,  the  buffer  contents  are 
printed  two  lines  below  the  previously  printed 
1  ine. 

PAGE  EJECT  -  If  the  terminal  supports  FORM 
FEEDS,  output  a  form  feed,  print  the  contents  of 
the  buffer,  and  output  a  carriage  return.  If 
the  terminal  does  not  support  FORM  FEEDS,  the 
driver  simulates  the  FORM  FEED  character  by 
either  outputting  four  line  feeds  to  a  crt 
terminal,  or  by  outputting  enough  line  feeds  to 
advance  the  paper  to  the  top  of  the  next  page  on 
a  printing  terminal. 

OVERPRINT  -  Print  the  contents  of  the  buffer  and 
output  a  carriage  return,  normally  overprinting 
the  previous  line. 

PROMPTING  OUTPUT  -  Output  one  line  feed  and 
print  the  contents  of  the  buffer.  This  mode  of 
output  is  intended  for  use  with  a  terminal  on 
which  a  prompting  message  is  output,  and  input 
is  then  read  on  the  same  line. 

INTERNAL  VERTICAL  FORMAT  -  Print  the  buffer 
contents  without  addition  of  vertical  format 
control  characters.  In  this  mode,  more  than  one 
line  of  guaranteed  contiguous  output  can  be 
printed  for  each  I/O  request. 
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All  other  vertical  format  control  characters  are  interpreted  as  blanks 
(040)  . 

A  task  can  determine  the  buffer  width  by  issuing  a  Get  LUN  Information 
cUrective  and  examining  word  5  returned  in  the  buffer. 

After  the  SET  has  been  done,  typing  beyond  the  buffer  width  results  in 
a  carriage  return  and  line  feed  being  output  before  the  next  character 
is  echoed.  Although  only  one  line  only  was  input,  it  is  displayed  on 
two  terminal  lines. 

It  is  possible  to  lose  track  of  where  you  are  in  the  input  buffer  if 
wrap-around  is  enabled  for  your  terminal.  For  example,  while  deleting 
text  on  a  wrapped  line,  the  cursor  will  not  back  up  to  the  previous 
line.  In  order  to  resynchronize  the  cursor  with  the  contents  of  the 
incomplete  input  buffer,  type  CTRL/R  (if  this  SYSGEN  option  has  been 
selected) . 


2.9   FEATURES  AVAILABLE  BY  RSX-llM  SYSGEN  OPTION 

A  number  of  terminal-driver  features  are  available  as   RSX-llM  SYSGEN 

options.    (See  the  RSX-llM  System  Generation  and  Installation  Guide) . 

Features  previously  discussed  that  are  not  repeated  Tn  this  section 
include : 

•  Some  device-specific  QIC  functions  (see  Section  2.3.2) 

•  Special  keys:     CTRL/R  --  Write  incomplete  input  buffer   (see 

Section  2.5.1) 

CRT  rubout  (see  Section  2.5.2) 

•  Escape  sequences  (see  Section  2.6) 

The  only  remaining  features  selected  at  SYSGEN  time  are 
terminal-independent  cursor  control  (described  in  Section  2.15), 
private  buffer  pool  size,  and  hard  receive  error  detection,  described 
in  the  following  sections. 


2.9.1   Private  Buffer  Pool  Size 

The  private  buffer  pool  is  contained  within  the  full-duplex  terminal 
driver.  The  size  of  the  whole  driver  is  established  during  SYSGEN  by 
the  VMR  command  to  load  the  driver  as  follows: 

LOA  TT:/SIZE=nnn 

The  private  buffer  pool  occupies  all  of  the  space  from  the  top  of  the 
actual  driver  code  up  to  nnn.  The  argument  nnn  is  expressed  i.  octal 
words,  and  the  maximum  value  is  20000,  corresponding  to  8K  words. 
Depending  on  driver  options  selected,  the  code  requires  from  2.5  to 
4.5k  words.  Thus,  the  maximum  buffer  pool  si7.<?  is  from  3.5k  to  5.5k 
words. 

Alternatively,  on  an  RSX-llM-PLUS  system,  it  is  possible  to  allocate 
the  private  pool  in  a  separate  common  block  called  TTCOM.  This  block 
can  range  in  size  up  to  4k  words.  The  default  size  is  4k  words,  but 
it  is  modifiable,  using  the  SIZE  keyword  with  the  VMR  LOA  command.  In 
this  case,  the  pri/ate  pool  is  used  almost  exclusively  for  data 
buffers.   Other  dr ^ver-specifc  data  is  allocated  from  secondary  pool. 


2-35 


PULL'DUPLEX  TERMINAL  DRIVER 

2.9.2  Hard  Receive  Error  Detection 

All  terminal  interfaces  supported  by  the  full-duplex  terminal  driver 
are  capable  of  detecting  and  flagging  hard  receive  errors.  Hard 
receive  errors  include  framing  errors,  enable  character  parity  error, 
and  data  overrun  error. 

NOTE 

The  driver  does  not   enable   parity 
generation  and  checking  on  DHll  and  DZll 
V  >  interfaces. 

If  the  hard  receive  error  detection  SYSGEN  option  (T$$RED)  is 
selected,  the  driver  handles  hard  receive  errors  as  follows: 

1.  If  a  read  request  is  being  processed  and  the  character  can  be 
processed  immediately,  the  read  request  is  terminated  with 
one  of  the  following  error  codes  returned  in  the  status 
block : 

Error  '  - 

Code  Hard  Receive  Error  i 

lE.BCC  Framing  error 

lE.DAO  Data  overrun 

lE.VER  Character  parity  error 

2.  If  a  command  line  is  being  input  for  a  command  line 
interpreter  task  and  the  character  can  be  processed 
immediately,  a  CTRL/U  is  simulated,  "U  is  echoed,  and  the 
input  is  terminated.   No  command  line  is  sent  to  the  task. 

3.  If  the  character  would  normally  cause  an  AST  if  no  error  was 
detected,  the  character  is  ignored  and  no  AST  occurs. 

4.  If  the  character  cannot  be  processed  immediately,  it  is 
stored  in  the  type-ahead  buffer.  A  flag  is  set  for  the  line,' 
indicating  that  the  last  character  in  the  type-ahead  buffer 
has  an  error,  disabling  further  storage  in  the  type-ahead 
buffer.  When  the  character  is  retrieved  from  the  buffer,  the 
appropriate  -2tlon  previously  described  is  taken  and  the  flag 
is  cleared.  Any  characters  received  in  the  meantime  are 
discarded,  with  a  bell  echoed  for  each  character. 

If  the  T$$RED  option  is  net  selected,  hard  receive  errors  are  ignored. 


2.10   TASK  BUFFERING  OF  RECEIVED  CHARACTERS 

When  task-buffering  received  characters,  characters  read  from  the 
terminal  are  sent  directly  to  the  task's  buffer.  Thus,  there  is  no 
need  to  allocate  a  terminal  driver  buffer.  ^, 

Task  buffering  of  received  characters  does  not  necessarily  reduce 
system  overhead.  For  example,  in  a  mapped  system  each  character  must 
be  mapped  to  the  task's  buffer.  However,  if  terminal  driver  buffering 
was  used,  the  mapping  is  only  done  once  for  all  characters  to  be 
transferred. 
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With  the  full  duplex  terminal  driver,  output  buffering  is  always 
performed.       .,         ^   . 

Task  buffering  is  overridden  during  checkpointing.  If  a  task  is 
checkpointable,  a  driver  buffer  is  allocated  and  the  task  is  made 
eligible  for  checkpointing  by  any  task,  regardless  of  priority,  while 
the  read  operation  is  in  progress.  (Checkpointing  only  occurs  in  this 
situation  when  there  is  another  task  that  can  be  made  active.)  Since 
checkpointability  is  controlled  by  the  task,  the  user  retains  control 
over  this  operation. 


2.11   TTPE-AHEAD  BOFFIiRIIIG 

Characters  received   oy  tha   terminal  driver  are  either  processed 

immediately  or  stored  in  the  type-ahead  buffer.  The  type-ahead  buffer 

allows  characters  to  be  temporarily  stored  and  retrieved  FIFO.  The 
type-ahead  buffer  is  us&d  as  follows: 

1.   Store  in  buffer: 

An  input  character  is  stored  in  the  type-ahead  buffer  if  one 
or  more  of  the  following  conditions  are  true: 

•  The  driver  is  not  ready   to  accept   the  character   (fork 
process  pending  or  in  progress)  . 

•  There   is   at   least  one  character   presently   in   the 
type-ahead  buffer. 

•  The  character  input  requires  echo  and  the  output   line   to 
the  terminal  is  presently  busy  outputting  a  character. 

•  Nc  read  request  is  in  progress,  no  unsolicited   input   AST 
is  specified,  and  the  terminal  is   attached. 

NOTE 

Depending  on  the  terminal  mode  and  the  presence  of  a 
read  function,  read  subfunctions  and  an  unsolicited 
input  AST,  the  CTRL/C,  CTRL/0,  CTRL/Q,  CTRL/S,  and 
CTRL/X  characters  may  be  processed  immediately  and 
not  stored  in  the  type-ahead  buffer. 

A  character  is  not  echoed  when  it  is  stored  in  the  buffer. 
Echoing  a  character  is  deferred  until  it  is  retrieved  from 
the  buffer,  since  the  read  mode  ffor  example, 
read-without-echo)  is  not  known  by  the  driver  until  then. 

2.   Retrieve  from  buffer: 

When  the  driver  becomes  ready  to  process  input,  or  when  a  task  issues 
a  read  request,  an  attempt  is  made  to  retrieve  a  character  from  the 
buffer.  If  this  attempt  is  successful,  the  character  is  processed  and 
echoed,  if  required.  The  driver  then  loops,  retrieving  and  processing 
characters  until  either  the  buffer  is  empty,  the  driver  becomes  unable 
to  process  another  character,  or  a  read  request  is  finished  with  the 
terminal  attached. 
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3.   Flash  the  buffer: 

The  buffer  is  flushed  (cleared)  when: 

1.  CTRL/C  is  received.  '  , 

2.  CTRL/X  is  received. 

3.  The  terminal  becomes  detached. 

Exceptions:  CTRL/C  and  CTRL/X  do  not  flush  the  buffer  if 
read-pass-all  or  read-with-special-terminators  is  in  effect. 

If  the  buffer  beconies  full,  each  character  that  cannot  be  entered 
causes  a  BELL  character  to  be  echoed  to  the  terminal. 

If  a  character  is  input  and  echo  is  required,  but  the  transmitter 
section  is  busy  with  an  output  request,  the  input  character  is  held  in 
the  type-ahead  buffer  until  output  (transmitter)  completion  occurs. 

2.12   POLL-DOPLEX  OPERATION 

When  a  terminal  line  is  in  the  full-duplex  mode,  the  full-duplex 
driver  attempts  to  simultaneously  service  one  read  request  and  one 
write  request.  The  Attach,  Detach  and  Set  Multiple  Characteristics 
functions  are  only  performed  with  the  line  in  an  idle  3tate  (not 
executing  a  read  or  a  write  request) . 


2.13   PRIVATI  BDFFER  POOL 

The  driver  has  a  private  buffer  pool  for  intermediate  input  and  output 
buffers  on  both  RSX-llM  and  RSX-llM-PLUS  systems,  and  type-ahead 
buffers  and  UCB  extensions  on  RSX-llM  systems  only.  Whenever  the 
driver  needs  dynamic  memory,  it  first  attempts  to  allocate  a  buffer  in 
the  private  pool.  If  this  fails,  a  second  attempt  is  made  in  the 
system  pool.  If  the  allocation  in  the  system  pool  fails  during 
command  line  input,  a  CTRL/U  is  simulated  and  echoed. 

Command  line  interpreter  task  buffers  are  handled  in  a  special  a; 
When  unsolicited  input  begins,  a  buffer  is  allocated,  as  previ  cs' 
described,  for  the  conmiand  line  (a  string  of  characters,  follcwei  hy 
an  appropriate  terminator  character).  When  the  input  is  completed, 
the  contents  of  the  buf  9r  is  sent  directly  to  the  command  line 
interpreter  task  if  th*»  hiiff«»r  uac  ai  ir.r.=.4-<a^  \r>  ^v««  rvr^^rr  ^f^^l  , 
However,  if  the  buffer  was  allocated  in  the  driver's  private  pool,  it 
must  first  be  moved  into  a  buffet  in  the  system  pool  to  provide  access 
for  the  task. 


2.14   INTERMEDIATE  INPUT  ANU  OOTPUT  BUFFERING 

Input  buffering  for  checkpointable  tasks  with  checkpointing  enabled  is 
provided  in  the  private  pool.  As  each  buffer  becomes  full,  a  new 
buffer  is  automatically  allocated  and  linked  to  the  previous  buffer. 
The  Executive  then  transfers  characters  from  these  buffers  to  the  task 
buffer  and  the  terminal  driver  deallocates  the  buffers  once  the 
transfer  has  been  completed. 
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If  the  driver  fails  to  allocate  the  first  input  buffer,  the  characters 
are  transferred  directly  into  the  task  buffer.  If  tne  first  buffer  is 
successfully  allocated,  but  a  subsequent  buffer  allocation  fails,  the 
input  request  terminates  with  the  error  code  IE. NOD.  In  this  case, 
the  I/O  status  block  contains  the  number  of  characters  actually 
transferred  to  the  task  buffer.  The  task  may  then  update  the  buffer 
pointer  and  byte  counc  and  reissue  a  read  request  to  receive  the  rest 
of  the  data.  The  type-ahead  buffer  ensures  that  no  input  data  is 
lost. 

All  terminal  output  is  buffered.  As  many  buffers  as  required  are 
allocated  by  the  terminal  driver  and  linked  to  a  list.  If  not  enough 
buffers  can  be  obtained  for  all  output  data,  the  transfer  is  done  as  a 
number  of  partial  transfers,  using  available  buffers  for  each  partial 
transfer.  This  is  transparent  to  the  requesting  task.  If  no  buffers 
can  be  allocated,  the  request  terminates  with  the  error  code  IE. NOD. 

The  unconditional  output  buffering  serves  three  purposes: 

1.  It  reduces  time  spent  at  system  state. 

2.  It  enables  long  DMA  transfers  for  DHll  controllers. 

3.  It  enables  task  checkpointing  during   the   transfer   to   the 
terminal  (if  all  output  fits  in  one  buffer  list). 


2.15   TERMINAL- INDEPKNOEHT  CORSOR  CONTROL 

Terminal-independent  cursor  control  capability  is  provided  at  SYSGEN 
time.  The  terminal  driver  responds  to  task  I/O  requests  for  cursor 
positioning  without  the  task  requiring  information  -bout  the  tyoe  of 
terminal  in  use.  I/O  functions  associated  with  cursor  positioning  are 
described  as  follows. 

Cursor  position  is  specified  in  the  vfc  parameter  of  the  lO.WLB  or 
10. RPR  function.  The  parameter  is  interpreted  simply  as  a  vfc 
parameter  if  the  high  byte  of  the  parameter  is  0.  However,  if  the 
parameter  is  used  to  define  cursor  position,  tht  high  byte  must  be 
nonzero,  the  low  byte  is  interpreted  as  column  number  (x-coordinate) , 
and  the  high  byte  is  interpreted  as  line  number  (y-coordinate) .  Home 
position,  the  upper  left  corner  of  the  display,  is  defined  as  1,1. 
Depending  upon  terminal  type,  the  driver  outputs  appropriate 
cursor-pos Ltioninq  commands  appropriate  for  the  terminal  in  use  that 
will  move  the  cursor  to  the  specified  position.  If  the  most 
significant  bit  of  the  line  number  is  set,  the  driver  clears  the 
display  before  positioning  the  cursor. 

When  defining  cursor  position  in  an  lO.WLB  function,  the  TF.RCU 
subfunction  can  be  used  to  save  the  current  cursor  position.  When 
included  in  this  manner,  TF.RCU  causes  the  driver  to  first  save  the 
current  cursor  position,  then  position  the  cursor  and  output  the 
specified  buffer,  and,  finally,  restore  the  cursor  to  the  original 
(saved)  position  once  the  output  transfer  has  been  completed. 


2.16   TERMINAL  INTERFACES 

This  section  summarizes  the  characteristics  of  the  standard 
communication-line  interfacets  supported  by  RSX-llM.  Refer  to  the 
Terminals  and  Communications  Handbook  for  additional  details. 
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2.16.1  DHll  Asynchronooa  Serial  Line  Multiplexer 

The  DHll  multiplexer  interfaces  up  to  16  asynchronous  serial 
communications  lines  for  terminal  use.  The  DHll  supports  programmable 
brud  rates.  Input  and  output  baud  irates  may  differ;  the  input  rate 
may  be  set  to  0  baud,  thus  effectively  turning  off  the  terminal.  The 
DMll-BB  option  may  be  included  to  provide  modem  control  for  dial-in 
lines.  These  lines  must  be  interfaced  by  means  of  a  full  duplex  modem 
(foi:  example,  in  the  United  States,  a  Bell  103A  or  equivalent  modem). 


2.16.2  UHVll  Asynchronous  Serial  Line  Multiplexer 

The  DHVll  multiplexer   interfaces   up  to  eight  asynchronous   serial 
communications   lines  for  terminal  use.   This  multiplexer  is  the  Q  BUS 


version  of  the  DHll  UNIBUS  multiplexer, 
prograiomable  baud  rates  with  the  option 
operation.  (Split  speed  operation  allows 
receive  speeds.)  Also  provided  is  modem 
point-to-point  operation. 


The  DHVll  supports 
of  selecting  split  speed 
different  transmit  and 
control   for  full-duplex 


• 


2.16.3  DJll  Asynchronous  Serial  Line  Multiplexer 

The  DJll  multiplexer  interfaces  as  m.any  as  16  asynchronous  serial 
lines  to  the  PDP-11  for  local  terminal  communications.  The  DJli  does 
not  provide  a  dial-in  capability.   Baud  rates  are  jumper  selectable. 


2.16.4  DLll  Asynchronous  Serial  Line  Interface 

The  DLll  supports  a  single  asynchronous  serial  line  and  handles 
communication  between  the  PDP-11  and  a  terminal.  A  number  of  standard 
baud  rates  are  available  to  DLll  users.  However,  since  the  DLll  does 
not  have  an  input  silo,  oaud  rates  greater  than  1200  baud  are  not 
recommended.   Higher  baud  rates  may  cause  input  characters  to  be  lost. 


• 


For  hardware  reasons,  a  DLll  is  susceptible  to 
interrupt  enable  in  its  Receiver  Status  Register, 
the  receiver  interrupt  bit  causes  the  terminal 
requests  but  not  to  respond  to  input  (for  example, 
not  e^ho  input  characters) .  The  terminal  driver  has 
recognizing  the  disabling.  Therefore,  it  cannot 
must  be  reset  with  an  MCR  OPEN  command,  the  console 
or  a  periodically  rescheduled  task. 


losing  receiver 
The  disabling  of 
to  print  output 
the  terminal  does 
no  mechanism  for 
recover.  The  bit 
switch   register. 


2.16.5  DZll  Asynchronous  Serial  Line  Multiplexer 

The  DZll  multiplexer  interfaces  up  to  eight  asynchronous  serial 
communication  lines  for  use  with  terminals.  It  supports  programmable 
baud  rates;  however,  transmit  and  receive  baud  rates  must  be  the 
same.   The  DZll  can  control  a  full  duplex  modem  in  auto-answer  mode. 
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2.17      PROGRAMHIIIG    HINTS 

2.17.1  Escape  Code  Conversion 

If  escape  sequences  are  recognized,  the  character  code  037  will 
terminate  input  and  a  status  code  IS. ESC  is  returned.  In  addition, 
character  codes  will  terminate  input  and  return  the  IS. ESC  status  if 
upper-  to  lowercase  conversion  is  not  enabled. 


2.17.2  RT02-C  Control  Function 

Because  the  screen  of  an  RT02C  Badge  Reader  and  Data  Entry  Terminal 
holds  only  one  line  of  information,  special  care  must  be  taken  when 
sending  a  control  character  (for  example,  vertical  tab)  to  the  RT02-C. 
Use  the  lO.WAL  (Write  All)  function  for  this  purpose. 

It  is  recommended  that  read  without  echoing  be  used  when  reading  a 
badge  with  the  RT02-C.  Use  lO.RAL  or  lO.RNE  functions,  followed  by 
the  lO.WAL  function,  to  echo  the  information  for  display. 
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2.17.3  Using  lO.WVB  Instead  of  lO.WLB 

Using  lO.WVB  instead  of  lO.WLB  is  recommended  when  writing  to  a 
terminal.  If  the  write  actually  goes  to  a  terminal,  the  Executive 
converts  the  lO.WVB  to  an  lO.WLB  request.  However,  if  the  LUN  has 
been  redirected  to  an  inappropriate  device  (for  example,  a  disk) ,  the 
use  of  an  lO.WVB  function  will  be  rejected  because  a  file  is  not  open 
on  the  LUN.  This  prevents  privileged  tasks  from  overwriting  block 
zero  of  the  disk. 

Note  that  any  subfunction  bits  specified  in  the  lO.WVB  request  (for 
example,  TF.CCO,  TF.WAL,  or  TF.WBT)  are  stripped  when  the  lO.WVB  is 
converted  to  an  lO.WLB. 


2.17.4  Remote  DLll-E,  DHll,  and  DZll  Lines 

Before  a  remote  line  is  answered,  the  driver  clears  certain  terminal 
characteristics  (see  Table  2-5)  that  may  have  been  set  by  an  MCR  SET 
command,  or  by  an  SF.SMC  function.  The  characteristics  cleared  are: 
TC.LCP,  TC.ESQ,  TC.HLD,  TC.SMR,  TC.NEC,  TC.FDX,  TC.HFF,  TC.HHT, 
TC.VFL,  TC.HFL,  TC.TTP,  TC.8BC,  and  TC.BIN.  (Clearing  TC.TTP  means 
that  a  terminal  type  of  "unknown"  will  be  returned  in  an  SF.GMC 
request.)  The  TC.ACR  characteristic  (automatic  wrap  around)  is  set. 
Buffer  size  is  set  to  72. 

A  DZll  remote  line  must  be  declared  to  be  remote  before  the  terminal 
driver  will  handle  the  modem. 


2.17.5  Side  Effects  of  Setting  Characteristics 

Certain  terminal  characteristics  that  a  task  may  set  or  that  an 
operator  may  set  using  MCR  commands  may  have  undesirable  side  effects. 
In  particular,  these  characteristics  include  the  hold-screen  mode  and 
the  lower-  to  uppercase  conversion  disable  mode.  Their  effects  are 
described  as  follows. 

TC.HLD  —  Unexpected  behavior  can  result  from  a  terminal  in  the 
hold-screen  mode  if  its  reception  rate  is  much  greater  than  its 
transmission  rate.  (The  DHll  supports  split  baud  rates.)  When  in  the 
hold-screen  mode,  the  terminal  automatically  sends  a  CTRL/S  during 
reception  of  an  output  stream  when  the  screen  is  nearly  full.  Output 
is  resumed  —  another  screen-full  —  when  you  type  SHIFT/SCROLL  (the 
terminal  generates  CTRL/Q) .  Thus,  no  output  is  lost  as  a  result  of 
scrolling  off  the  screen  before  you  can  read  it.  However,  if  the 
terminal's  transmission  rate  is  far  below  its  reception  rate,  some 
unread  output  may  scroll  out  of  sight  before  the  CTRL/S  can  be 
transmitted. 

Note  that  some  terminals  and  interfaces  are  hardware  buffered.  This 
can  cause  obscure  timing  problems  for  tasks  that  attempt  to  invoke  the 
hold-screen  mode. 

TC.SMR  —  If  this  characteristic  is  asserted  (lower-  to  uppercase 
conversion  is  disabled),  octal  characters  175  and  176  are  interpreted 
as  "right  brace  (  j  )"  and  "tilde  (<^) ,'  respectively.  If  TC.SMR  is 
not  asserted,  these  characters  are  interpreted  as  an  Altmode  (that  is, 
they  function  as  line  terminators  that  do  not  advance  the  cursor  to  a 
new  line) . 
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2.17.6  Modem  Support 

The  terminal  driver  supports  the  following  modem  control  operations: 

•  Local  or  remote  operation 

•  Answer  speed 

•  Auto-baud  speed  detection 

The  characteristics  bit  that  controls  local  or  remote  operation  is 
TC.DLU.  This  bit  can  be  set  with  the  MCR  command  SET  /REMOTE  (or  SET 
/NOREMOTE  for  local  operation).  The  DCL  command  SET  TERMINAL  REMOTE 
(or  SET  TERMINAL  LOCAL)  can  also  be  used. 

When  there  ir  an  incoming  call  on  a  remote  line,  the  TC.ASP 
characteristic  determines  the  baud  rate  for  the  answering  modem. 

Split  baud  rates  (different  transmit  and  receive  speeds)  are  not 
supported  for  answer  speed. 

The  default  answer  speed  is  set  at  SYSGEN  time.  However,  the  answer 
speed  can  be  set  on  line  using  the  MCR  command  SET  /REMOTE=TTnn : speed. 
VMR  can  also  be  used  to  set  the  answer  speed. 

The  terminal  driver  can  determine  the  speed  of  the  incoming  call  by 
sampling  the  first  input  character  after  dial-up  for  the  following 
speeds : 

110 
150 
300 
1200 

This  is  called  auto-baud  speed  detection.  This  option  can  be  selected 
for  each  line  using  the  SET  /ABAUD  command.  This  command  sets  the 
TC.ABD  terminal  characteristic.  When  TC.ABD  is  set  for  a  given  line, 
the  terminal  driver  makes  three  attempts  to  determine  the  incoming 
speed.  If  the  auto-baud  speed  detection  fails,  the  terminal  driver 
will  use  the  default  answer  speed  discussed  above. 

For  auto-baud  speed  detection  to  work  correctly,  the  first  -.nput 
character  after  dial-up  must  be  either  carriage  retMrn  or  CTRL/C 
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3.1   INTRODUCTION   .   ' 

The  half-duplex  terminal  driver  provides   support   for  a   variety  o 
terminal   devices   under   RSX-llM.    (This   terminal   <?river   is  not 
supported  on  RSX-llM-PLUS  systems.)  The  half-duplex  terminal  driver  is 
generally   used   in   RSX-llM  systems  where   small  driver  size   is 
essential,  and  the  additional  functional  capability  provided   by 
larger   full-duplex   terminal   driver   (described  in  Chapter  2)  is 
required.   Table   3-1   summarizes   the   terminals   supported, 
subsequent  sections  describe  these  devices  in  greater  cetail. 

Table  3-1 
Supported  Terminal  Devices 


the 
not 
and 


Model 

Columns 

Lines/ 
Screen^ 

Character 
Set 

Baud 
Range 

Upper-  & 

Lowercase? 

Send 

Receive 

ASR-33/35 

72 

64 

110 

KSR-33/35 

72 

64 

110 

LA12 

132 

96 

50-9600 

yes 

yes 

LAIOO 

132 

96 

110-9600 

yes 

yes 

LA30-P 

80 

64 

300 

LA30-S 

80 

64 

110-300 

LA34 

132 

96 

110-300 

yes 

yes 

LA36 

80-132 

64-96 

110-300 

yes 

yes  2 

LA38 

132 

96 

110-300 

yes 

yes 

LA120 

132 

96 

50-9600 

yes 

yes 

LA180S 

132 

96 

300-9600 

yes 

RT02 

64 

1 

64 

110-1200 

RT02-C 

64 

1 

64 

110-1200 

VT05B 

72 

20 

64 

110-2400 

yes 

VT50 

80 

12 

64 

110-9600 

VT50H 

80 

12 

64 

110-9600 

VT52 

80 

24 

96 

110-9600 

yes 

yes 

VT55 

80 

24 

96 

110-9600 

yes 

yes 

VT61 

80 

24 

96 

110-9600 

yes 

yes 

VTiOO 

80-132 

24 

96 

50-9600 

yes 

yes 

VTlOl 

80-132 

24 

96 

50-19200 

yes 

yes 

VT102 

80-132 

24 

96 

50-9600 

yes 

yes 

VT10  5 

80-132 

24 

96 

50-9200 

yes 

yes 

VT12  5 

80-132 

24 

96 

50-9600 

yes 

yes 

VT131 

80-132 

24 

96 

50-19200 

yes 

yes 

VT13  2 

80-132 

24 

96 

50-19200 

1 

yes 

yes 

1.  Applies  only  to  video  terminals. 

2.  Only  for  96-character  terminal. 
the   terminal  interfaces  summarized 
are  described  in  greater  detail  in 
identical  for  all. 


The  terminal 
in  Table  3-2. 
Section   3.9. 


driver   supports 

These  interfaces 

Programming   is 
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Table  3-2 
Standard  Terminal  Interfaces 


Model 

Type 

DHll 

DHll-DMll-BB 

DJll 

DLll-A/B/C/D/W 

DLVll-F 

DZll 

16-line  multiplexer^ 

16-line  multiplexer  with  modem  control^ 

16-line  multiplexer 

Single-line  interfaces 

Single-line  interface 

8-line  multiplexer  with  modem  control^ 

1.  Direct  memory  access  (DMA)  not  supported. 

2.  Full-duplex  control  only.   For  example,   in   the   USA,   a 
Bell  103A-type  modem. 


Terminal  input  lines  can  have  a  maximum   length  of   255   bytes   (the 

maximum   is  set   in   the   system  generation,  or  SYSGEN,  dialog).   The 

extra  characters  of  an  input  line   that   exceeds  the  maximum   length 
generally  become  an  unsolicited  input  line. 


3.1.1  ASR-33/35  Teletypes^ 

The  ASR-33  and  ASR-35  Teletypes  are  asynchronous,  hard-copy  ter'".inals. 
No  paper  tape  reader  or  punch  capability  is  supported. 


3.1.2  KSR-33/35  Teletypes!  '  - 

The  KSR-33  and  KSR-35  Teletypes  are  asynchronous,  hard-copy  terminals. 


J. 1.3   LA30  DECwr Iters  " 

The  LA30  DECwriter  is  an  asynchronous,  hard-copy  terminal  that  \ s 
capable  of  producing  an  original  and  one  copy.  The  LA30-P  is  a 
parallel  model  and  the  LA30-S  is  a  serial  model. 


3.1.4  LA36  DECwriter 

The  ':.A36  DECwriter  is  an  asynchronous  terminal  that  produces  hard  copy 
and  operates  in  serial  mode.  It  has  an  impact  printer  capable  of 
generating  multipart  and  special  preprinted  forms.  The  LA36  can 
receive  and  transmit  both  uppercase  and  lowercase  characters. 


1.    Teletype    is 


-^jistered    trademark   of   the   Teletype   Corporation, 
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3.1.5   LA120  DECwrlt«r 

The  LA120  DECwriter  is  a  hard-copy,  upper-  and  lowercase  terminal 
capable  of  printing  multipart  forms  at  speeds  up  to  180 
characters-per-second .  Serial  communications  speed  is  selected  from 
14  baud  rates  ranging  from  50  to  9600  bps.  Hardware  features  allow 
bidirectional  printing  for  maximum  printing  speed,  and  also  allow 
user-selected  features,  including  font  size,  line  spacing,  tabs, 
margins,  and  forms  control.  These  functions  can  also  be  set  up  by 
user  tasks  that  issue  appropriate  ANSI-standard  escape  sequences. 


3.1.6   LA180S  DECprinter 

The  LA180S  DECprinter  is  a  serial  version  of  the  LA180.  It  is  a 
print-only  device  (it  has  no  keyboard)  that  can  generate  multipart 
forms.   The  LA180S  can  print  uppercase  and  lowercase  letters. 


:i.l.7   RT02  Alphanumeric  Display  Terminal   and   RT02-C   Badge   Reader/ 
Alphanumeric  Display  Terminal 

The  RT02  is  a  compact,   alphanumeric  display   terminal   designed   for 
applications   in   which  source  data  is  primarily  numeric.   A  shift  Key 
permits  the  entry  of   30   discrete   characters,   including   uppercase 
alphabetic  characters.   The  RT02  can,  however,  receive  and  display  64 
characters. 

The  RT02-C  model  also  contains  a  badge  reader.  This  option  provides  a 
reliable  method  of  identifying  and  controlling  access  to  the  PDP-' 1  or 
to  a  secure  facility.  Furthermore,  data  in  a  format  corresponding  to 
that  of  a  badge  (22-column  fixed  data)  can  be  entered  quickly. 


3.1.8  VTOSB  Alphanumeric  Display  Terminal 

The  VT05B  is  an  alphanumeric  display  terminal  that  consists  of  ii  CRT 
display  and  a  self-contained  keyboard.  From  a  programming  point  of 
view,  it  is  equivalent  to  other  terminals,  except  that  the  VT05B 
offers  direct  cursor  addressing. 


3.1.9  VT50  Alphanumeric  Display  Terminal 

The  VT50  is  an  alphanumeric  display  terminal  that  consists  of  a  CRT 
display  and  a  keyboard.  It  is  similar  to  the  VT05B  in  operation,  bat 
does  not  offer  direct  cursor  addressing. 


3.1.10  VT50H  Alphanumeric  Display  Terminal 

The  VT50H  is  an  alphanumeric  display  terminal  with  CRT  display, 
keyboard,  and  numeric  pad.  It  oiCers  direct  cursor  addressing.  (The 
VT50H's  direct  cursor  addressing  is  not  compatible  with  that  of  the 
VTOSB, ) 
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3.1<11  VT52  Alphanumeric  Display  Terminal 


The  VT52  is  an  upper-  and  lowercase  alphanumeric  terminal  with  numeric 
pad  and  direct  cursor  addressing.  (The  VT52's  direct  cursor 
addressing  is  compatible  with  that  of  the  VT50H,  but  not  with  that  of 
the  VT03B.)  The  VT52  can  be  configured  with  a  built-in  thermal 
printer. 


3.1.12  VT55  Graphics  Display  Terminal 

The  VT55  is  similar  to  the  VT52  in  its  operation  as  an  alphanumeric 
terminal.  The  VT55  offers  graphics  display  features  that  are  not 
supported  by  ftSX-llM,  although  the  system  allows  a  knowledgeable  task 
to  access  the  explicitly  special  features  of  the  VT55. 


3.1.13  VT61  Alphanumeric  Display  Terminal 

The  VT61  is  an  "intelligent"  upper-  and  lowercase  alphanumeric 
terminal  with  an  integral  microprocessor.  It  offers  two  128-member 
character  sets  and  numerous  built-in  functions  for  editing  and 
preparing  forms,  as  well  as  a  block-transfer  mode.  (None  of  these 
special  features  is  supported  by  RSX-llM.) 


3.1.14   VTIOO  DECscope 

The  VTIOO  DECscope  is  an  upper-  and  lowercase  alphanumeric 
keyboard/video  display  terminal.  It  is  capable  of  displaying  24  lines 
of  80  characters  (each  line).  Serial  communications  speed  is  selected 
from  baud  rates  ranging  from  50  to  9600  bps.  Hardware  features  allow 
user  selection  of  display  characteristics  and  functions  including 
smooth  scroll,  reverse  video,  and  so  forth.  These  functions  can  also 
be  set  up  by  user  tasks  that  issue  appropriate  ANSI-standard  escape 
sequences. 


3.2   GET  LUN  INFORMATION  MACRO 

Word  2  of  the  buffer  filled  by  the  Get  LUN  Information  system 
directive  (the  first  characteristics  word)  contains  the  following 
information  for  terminals.  A  setting  of  1  indicates  that  the 
described  characteristic  is  true  for  terminals. 

Bit  Setting  Meaning 

0  1  Record-oriented  device 

1  1  Carriage-control  device 

2  1  Terminal  device 

3  0  File  structured  device 
^          9  Single-directory  device 

M-  0  Sequential  device 

8  0  Mass  storage  device 
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Bit 

Setting 

7 

0 

8 

0 

9 

0 

10 

0 

11 

0 

12 

0 

13 

0 

14 

0 

15 

0 

Haaning 

User-mode  diagnostics  supported 

Device  supports  22-bit  direct  addressing 

Unit  software  write-locked 

Input  spooled  device 

Output  spooled  device 

Pseudo  device 

Device  mountable  as  a  communications 
channel 

Device  mountable  as  a  FILES-11  volume 

Device  mountable 


• 


Words  3  and  4  are  undefined.  Word  5  indicates  the  default  buffer 
size  for  the  device:  for  terminals  the  width  of  the  terminal  carriage 
or  display  screen. 


3.3   010  MACRO 

Table  3-3  lists  the  standard  and  device-specific  functions  of  the  QIO 
macro  that  are  valid  for  terminals.  All  device-specific  functions  are 
options  that  may  be  selected  at  system  generation. 

Two  device-specific  functions,  SF.SMC  and  SF.GMC,  have  nonstandard 
function  names.   These  names  are  designed  for  compatibility  with  IAS. 

Table  3-3 
Standard  and  Device-Specific  QIO  Functions  for  Terminals 


Format 

Function 

STANDARD  FUNCTIONS: 

QIOSC 

10. ATT,... 

Attach  device 

OIO$C 

lO.DET, . . . 

Detach  device 

QIOSC 

lO.KIL,... 

Cancel  I/O  requests 

QIOSC 

lO.RLB, . . . ,<stadd,size> 

READ  logical  block 

(read  typed  input  into  buffer) 

QIOSC 

lO.RVB, . . . ,<stadd,size> 

READ  virtual  block 

(read  typed  input  into  buffer) 

QIOSC 

lO.WLB,. . • ,<stadd,slze,vfc> 

WRITE  logical  block 
(print  buffer  contents) 

QIOSC 

lO.WVB, . . . ,<stadd,size,vfc> 

WRITE  virtual  block 
(print  buffer  contents) . 

(continued  on  next  page) 
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Table  3-3   (Cont.) 
Standard  and  Device-Specific  QIO  Functions  for  Terminals 


Format 

Function 

DEVICE-SPECIFIC  FUNCTIONS 
(ALL  SYSGEN  OPTIONS): 

QIOSC 

10. ATA, . . . ,<ast> 

ATTACH     device,      specify 
unsolicited-    input-character 
AST 

0IO$C 

lO.CCO, .. . ,<stadd,3ize,vfc> 

CANCEL  CTRL/O  (if   in   effect), 
then  write  logical  block 

0IO$C 

SF.GMC, . . . ,<stadd,size> 

GET  multiple  characteristics 

QIO$C 

10. GTS, . . . ,<stadd,size> 

GET  terminal  support 

0IO$C 

lO.RAL, .. . ,<stadd,size> 

READ  logical   block,   pass  all 
bits 

OIOSC 

lO.RNE, .. . ,<stadd,si  ze> 

READ  logical  block,  do  not  echo 

OIOSC 

10. RPR, . . . ,<stadd ,size, 
[tmo] ,pradd,prsize,vfc> 

READ  logical  i lock  after  prompt 

QIOSC 

lO.RST, . . . ,<stadd,size> 

READ  logical   block   ended   by 
special  terninators 

0IO$C 

SF.SMC, .. . ,<stadd,size> 

SET  multiple  characteristics 

0IO$C 

lO.WAL, . . . ,<stadd,size> 

WRITE  logical  block,   pass  all 
bits 

QIOSC 

lO.WBT, . . . ,<stadd ,size,vfc> 

WRITE   logical   block,   break 
through  most  I/O  conditions  at 
terminal 

ast 


The  entry  point  for  an  unsolicited-input-character  AST. 


pradd 


The  starting  address  of  the  byte  buffer  where   the   prompt   is 
stored.   The  buffer  must  be  within  the  task's  address  space. 


prsize 


The  size  of  the  pradd  prompt  buffer  in  bytes.  If  the  system 
supports  variable  length  reads,  the  buffer  size  must  be  greater 
than  0  and  less  than  or  equal  to  255.  If  the  system  does  not 
support  variable  length  reads,  the  specified  size  must  be  greater 
than  0  and  less  than  or  equal  to  80. 
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The  size  of  the  stadd  data  buffer  in  bytes  (must  be  greater  than 
0)  .  If  the  function  Is  a  read  and  the  system  supports 
variable-length  reads,  the  size  must  be  less  than  or  equal  to 
255.  Otherwise,  the  size  must  be  less  than  or  equal  to  80.  The 
buffer  must  be  within  the  task's  address  space.  For  SF.GMC, 
10. GTS,  and  SF.SMC,  the  size  must  be  an  even  number  less  than 
40fi5  (decimal).  If  the  function  is  a  write,  size  can  be  up  to 
32K  bytes. 


stadd 


tmo 


vfc 


The  starting  address  of  the  data  buffer.  The  address  must  be 
word  aligned  for  SF.GMC,  10. GTS,  and  SF.SMC;  otherwise,  stadd 
may  be  on  a  byte  boundary. 


An  optional  time-out  count,  included  for  IAS  compatibility.    If 
supplied,  it  is  ignored. 


A  character  for  vertical  format  control   from  Table   3-11   (see 
Section  3.7)  . 


3.3.1   Subfunction  Bits 

Most  of  the  device-specific  functions  supported  by  the  terminal  driver 
are  implemented  by  way  of  "subfunction  bits."  That  is,  these  functions 
can  be  invoked  by  ORing  a  named  bit  with  some  other  function.  Table 
3-4  shows  the  relationship  of  the  10  subfunction  bits  to  the  standard 
and  device-specific  functions. 

The  10  subfunction  bits,  and  their  octal  values,  are: 

TF.AST  Unsolicited-input-character  AST     10 

TF.BIN  Binary  prompt  2 

TF.CCO  Cancel  CTRL/0  40 

TF.ESO  Recognize  escape  sequences  20 

TF.RAL  Read  all  bits  10 

TF.RNE  Read  with  no  echo  20 

TF.RST  Read  with  special  terminators  1 

TF.WAL  Write  all  bits  10 

TF.WBT  Break-through  write  100 

TF.XOF  Send  XOFF  100 

The  subfunction  bits  are  defined  in  the  system  module  TTSYM  (discussed 
further  in  Section  3.3.2.5).  The  octal  values  of  these  entities  are 
subject  to  change;  therefore,  it  is  recommended  that  you  always  use 
the  symbolic  names.  As  Tatle  3-4  shows,  7  of  the  10  subfunction  bits 
can  be  ORed  with  standard  QIO  functions  to  invoke  device-specific 
functions.  The  remaining  three  subfunction  bits  (TF.BIN,  TF.ESQ,  and 
TF.XOF)  can  be  ORed  with  Attach  and  Read  After  Prompt  QIOs  to  pr^^vide 
added  features,  as  described  in  Section  3.3.2. 
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Of  the  10  subfunction  bits,  3  can  be  used  with  Read  QIO  functions,  3 
with  Write  functions,  2  with  Attach  functions,  and  5  with  Read  After 
Prompt.   The  breakdown  is: 

Read  TF.RAL,  TF.RNE,  TF.RST 

Write  TF.CCO,  TF.WAL,  TF.WBT 

Attach  TF.AST,  TF.ESQ 

Read  After  Prompt     TF.BIN,  TF.XOF,  TF.RAL,  TF.RNE,  TF.RST 

If  a  task  invokes  a  subfunction  bit  that  is  not  supported  on  the 
system,  the  subfunction  bit  is  ignored,  not  rejected.  For  example,  if 
Read  with  Special  Terminators  is  not  selected,  either  lO.RST  or 
lO.RLBlTF.RST  is  interpreted  as  lO.RLB. 

The  following  example  shows  a  QIO  request  using  more  than  one 
subfunction  bit:  a  nonechoed  read,  which  may  be  concluded  by  a 
special  terminator,  after  a  prompt. 

0IO$C  10. RPR! TF.RNE! TF.RST, . . . ,<stadd ,si ze , ,pradd ,prsl ze ,vfc> 


3.3.2  Details  on  Device-Specific  QIO  Functions 

All  the  device-specific  functions  described  in  this  section  are  SYSGEN 
options.  All  except  SF.GMC,  10. RPR,  SF.SMC,  and  10. GTS  can  be  issued 
by  ORing  a  particular  u.ubfunction  bit  with  another  QIO  function. 
These  subfuaction  bits  are  specified  in  the  text;  subfunction  bits 
are  described  in  general  in  Section  3.3.1. 

In  addition  to  the  11  device-specific  QIO  functions,  this  section  also 
gives  details  on  the  features  provided  by  the  3  subfunction  bits 
TF.ESQ,  TF.BIN,  and  TF.XOF. 


3.3.2.1  10. ATA  -  10. ATA  is  a  variation  of  the  Attach  directive.  It 
specifies  an  asynchronous  system  trap  (AST)  to  process  an  unsolicited 
input  character.   When  called  as  follows: 

QIOSC    lO.ATA, . . . ,<ast> 

this  function  attaches  the  terminal  and  identifies  "ast"  as  the  .ntry 
point  for  an  unsolicited-input-character  AST.  Control  passes  to  this 
address  whenever  any  unsolicited  character  (other  than  CTRL/Q,  CTRL/S, 
or  CTRL/O)  is  input.  Note  that  little  checking  is  done  on  the 
specific  AST  address.  A  bad  address  is  frequently  detected  only  when 
the  Executive  tries  to  transfer  control  to  it  and  the  task  crashes. 

In  particular,  CTRL/C  is  trapped  by  the  task  and  does  not  reach  MCR. 
Thus,  any  task  that  uses  10. ATA  should  recognize  some  input  sequence 
as  a  request  to  terminate,  because  MCR  can  not  be  invoked  to  abort  the 
task  in  case  of  difficulty. 

Note  that  this  mechanism  is  intended  to  get  a  single  character  into 
the  system  --  not  a  series  of  characters.  Since  the  driver  must 
become  a  fork  process  in  order  to  declare  an  AST,  a  second  character 
can  arrive  before  the  driver  can  queue  an  AST  for  the  first  character. 
The  buffer  for  unsolicited  input  characters,  however,  is  one  byte 
long.  Therefore,  the  terminal  driver  ignores  the  second  character. 
This  circumstance  can  occur  because  of  fast  input  on  a  busy  system  or 
because  output  is  in  progress  when  the  characters  are  received.  The 
implications  of  this  are  that  neither  type-ahead  nor  full-duplex 
operations  can  be  simulated  perfectly  using  unsolicited  character 
ASTs, 
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Table  3-4 
Cubfunction  Bits 


I 


Function 

Equivalent  with 
subfunction  bits 

Allowed  Subfunction 

Bits 

TF . AST 

TF.BIN 

TF.CCO 

TF.ESQ 

TF.RAL 

TF.SNE 

TF.RST 

TF.WAL 

TF.WBT 

TF.XOF 

STANDARD  FUNCTIONS 

X 

X 

10. ATT 

lO.DET 

lO.KIL 

lO.RLB 

1 

X 

1 

lO.RVB 

2 

2 

2 

lO.WLB 

X 

X 

X 

lO.WVB 

2 

X 

2 

2 

DEVICE-SPECIFIC  FUNCTIONS 

10. ATA 

lO.ATT'TF.AST 

lo.cro 

lO.WLBlTF.CCO 

X 

X 

SF.GMC 

10. GTS 

lO.RAL 

lO.RLBlTF.RAL 

X 

1 

lO.RNE 

lO.RLBlTF.RNE 

1 

1 

10. RPR 

X 

1 

X 

1 

X 

lO.RST 

lO.RLBITF.RST 

1 

X 

SF.SMC 

lO.WAL 

lO.WLBlTF.WAL 

X 

X 

I0.WB7 

lO.WLBlTF.WBT 

X 

X 

8 


3 


1.  Exercise  great  care  when  using  R^ad  All  and  Read  with  Special  Terminators  together.   Obscure  problems  can 
result. 

2.  These  subfunction  bits  are  allows^  but  are  not  effective.   They  are  stripped  off  when  the  read   or   write 
virtual  Is  converted  to  a  read  or  write  logical. 
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At  entry,  the  unsolicited  character  is  ^he  low-order  byte  of  the  top 
word  on  the  stack.  Before  exiting  the  AST,  be  sure  to  pop  that  word 
off  the  stack;  otherwise,  the  task  will  crash.  In  all  other  respects 
the  AST  environment  is  standard: 

SP+IO  Event  flaq  mask  word 

SP+06  PS  of  task  prior  to  AST 

SP+04  PC  of  task  prior  to  AST 

SP-»-02  Task's  directive  status  word 

SP-t-00  Unsolicited  character  in  low  byte 

See  the  RSX-llM/M-PLUS  Executive  Reference  Manual  for  further  details 
on  ASTs^  See  Section  3.10.10  for  hints  on  ASTs  in  a  multiterminal 
envi  ronment . 

10. ATA  is  equivalent  to  10. ATT  ORed  with  the  subfunction  bit  TF.AST. 


3.3.2.2  lO.ATTITF.ESQ  -  The  task  issuing  this  directive  attaches  a 
terminal  and  notifies  the  driver  that  it  recognizes  escape  sequences 
input  from  that  terminal.  Escape  sequences  are  recognized  only  for 
solicited  input.  See  Section  3.6  for  a  discussion  of  escape 
sequences. 

If  the  terminal  has  not  been  declared  capable  of  generating  escape 
sequences,  10. ATT! TF. ESQ  has  no  eff  t  beyond  attaching  the  terminal. 
No  escape  sequences  are  returned  to  e  task,  because  any  ESC  sent  by 
the  terminal  acts  as  a  line  terminator.  The  SF.SMC  QIO  or  the  MCR  SET 
/ESCSFO  command  is  used  to  declare  the  terminal  capable  of  generating 
escape  sequences  (see  Table  3-5  and  Section  3.3.2.12). 


3.3.2.3  10. ceo  -  This  write  function  directs  the  driver  to  write  to 
the  terminal  regardless  of  a  CTRL/0  condition  that  may  be  in  effect. 
If  CTRL/0  is  in  effect,  it  is  canceled  before  the  write  is  done. 

10. ceo  is  equivalent  to  lO.WLBlTF.CCO. 

3.3.2.4  SF„GMC  -  The  Get  Multiple  Characteristics  .unction  returns 
information  on  terminal  characteristics.  Get  Multiple  Characteristics 
is  used  in  the  following  way: 

QIO$C  SF.GMC, . . .  ,<stadd ,size> 

stadd 

The  starting  address  of  a  data  buffer   of   length   "size"   bytes. 
Each  word  in  the  buffer  has  the  form 

.BYTE  characteristic-name 
.BYTE   0 

ch<)racteri8tic-nffine 

One  of  the  eight  bit  names  given  in  Table  3-5. 
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The  010  function  returns  a  value  in  the  high-order  byte  of  each 
byte-pair:  1  if  the  characteristic  Is  true  for  the  terminal,  0  if  not 
true. 


For  the  TC.TTP  characteristic  (terminal  type)  ,  one  of  thr>ie  values 
returned  In  the  high-order  byte,  as  shown  In  Table  3-6. 


is 


NOTE 

The  half-duplex  terminal  driver  treats 
the  terminal  type  as  a  required 
characteristic  for  the  type  of  terminal 
specified.  The  terminal  type  (TC.TTP) 
does  not  set  any  implicit  terminal 
characteristics  other  than  those  noted 
in  Table  3-6. 


Table  3-5 
Terminal  Characteristics  for  SF.GMC  and  SF.SMC  Requests 


Bit 

Octal 

Me  Tiling 

Corresponding 

Name 

Value 

(If  Asserted):   Terminal  ... 

MCR  Command 

TC.ASP3 

76 

Remote  line  answer  speed 

SET  /REMOTE=TI:speed 

TC.ESQ 

35 

...can  generate  escape  sequences 

SET  /ESCSEQ-TI: 

tc.hldI 

44 

...is  in  hold-screen  mode 

SET  /HOLD-TI: 

TC.NEC 

47 

...is  in  no-echo  mode 

SET  /NOECHO-TI: 

TC.PRl2 

bl 

.is  privileged 

SET  /PRIV-TTnn: 

TC.SCP 

12 

.  .  .is  c:  scope  (CRT) 

SET  /CRT«TI: 

TC.SLV 

50 

...  is  slaved 

SET  /SLAVE-TTnn: 

TC.SMR 

25 

Uppercase  conversion  disabled 
on  input 

SET  /LOWER-TI: 

TC.TTP 

10 

Terminal  type 

SET  /LA30S-TI: 
SET  /VT05B-TI: 

TC.HFF 

17 

...handle  hardware  form  feeds 

SET  /FORMFEED-TI: 

TC.RSP3 

3 

Receiver  speed 

SET  /SPEED=TI:rcv:xmit 

TC.XSp3 

4 

Transmitter  speed 

(As  above) 

1.  Effective  for  VT5x  and  VT61  only. 

2.  Cannot  be  changed  by  a  task;   must  use  MCR  command, 

3.  Recognized  only  by  the  SF.SMC  function. 


Table  3-6 
Bit  TC.TTP  (Terminal  Type):  Values  Set  by  SF.SMC 
and  Returned  by  SF.GMC 


Octal  Value 

Symbolic 

Meaning 

0 

T.UNKO 

Terminal  type  is  unknown 
(resets  all  other  types) 

1 

T.AS33 

Terminal  is  an  ASR 

(sets  uppeicase  conversion  on 

-  - 

output) 

4 

T.L30S 

Terminal  is  an  LA 30 

_ 

(sets  horizontal  fill  after 

carriage  return) 

7 

T.VT05 

Terminal  is  a  VT05B 

(sets  a  vertical  fill  count  of 

4) 
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3.3.2.5  10. GTS  -  The  G»t  Terminal  Support  QIO  returns  a  4-word  buffer 
of  information  specifying  which  SYSGEN-option  features  are  part  of  the 
terminal  driver.  Of  these  four  words,  two  are  currently  defined. 
Table  3-7  gives  details  on  these  two  woros.  The  10. GTS  QIO  is  itself 
a  SYSGEN  option.  Tf  10. GTS  Is  issued  on  a  minimum  system  (one  with  no 
terminal-driver  SYSGEN  options),  lE.IFC  is  returned  in  the  I/O  status 
block. 


Table  3-7 
Information  Returned  by  Get  Terminal  Support  (10. GTS)  QIO 


Bit 

Value 

Mnemonic 

Meaning  When  Set  to  1 

Word 

0  of  Bui 

ffer: 

0 

1 

Fl.ACR 

Automatic  CK/LF  on  long  lines 

1 

2 

Fl.BTW 

Break-through  write 

2 

4 

Fl.BUF 

Checkpointing  during  terminal  input 

3 

10 

Fl.'JJA 

Unsolicited-input-character  AST 

4 

20 

Fl.CCO 

Cancel  CTRL/O  before  writing 

5 

40 

Fl.ESQ 

Recognize  escape  sequences  in  solid 

ted  input 

6 

100 

Fl.HLD 

Hold-screen  mode 

7 

200 

Fl.LWC 

Lower-  to  uppercase  conversion 

8 

400 

Fl.RNE 

Read  with  no  echo 

9 

1000 

Fl.RPR 

Read  after  prompting 

10 

2000 

Fl.RST 

Read  with  special  terminators 

11 

4000 

Fl.RUB 

CRT  rubout 

12 

10000 

Fl.SYN 

CTRL/R  terminal  synchronization 

13 

20000 

Fl.TRW 

Read  all  and  write  all 

14 

40000 

F 1 . UTB 

Input  characters  buffered  in  task's 
space 

address 

15 

100000 

Fl.VBF 

Variable-length  terminal  buffers 

Word 

1  of  Bul 

1 

Efer: 

F2.SCH 

Set  characteristics  QIO  (SF.SMC) 

0 

' 

2 

F2.GCH 

Get  characteristics  QIO  (SF.GMC) 

The  various  symbols  used  by  the  10. GTS,  SF.GMC,  and  SF.SMC  QIOs  are 
defined  in  a  system  module,  TTSYM.  These  symbols  include:  Fl.xxx  and 
F2.XXX  (Table  3-7);  T.xxxx  (Table  3-fi) ;  TC.xxx  (Table  3-5);  and  the 
SE.xxx  error  returns  described  in  Table  3-8,  Section  3.4.  These 
symbols  may  be  defined  locally  within  a  code  module  by  using: 


.MCALL    TTSYMS 


TTSYM $ 


If  the  symbols  are  not  defined  locally,  they  are  automatically  defined 
by  the  Task  Builder. 


The  octal  values  of  these  symbols  are  subject  to  change, 
it  is  recommended  that  you  always  use  the  symbolic  names. 


Therefore, 
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3.3.2.6  lO.RAL  -  The  Read  All  function  causes  the  driver  to  pass  all 
bits  to  the  requesting  taste.  The  driver  does  not  intercept  control 
characters  or  mask  out  the  "parity"  (high-order)  bit.  This  means,  for 
example,  that  CTRL/C,  CTRL/Q,  CTRL/S,  CTRL/0,  and  CTRL/Z  are  passed  to 
the  program  and  are  not  interpreted  by  the  driver. 

NOTE 

lO.RAL  echoes  the  characters  that  are 
read.  To  read  all  bits  without  echoing, 
use  lO.RALITF.RNE. 

lO.RAL  is  equivalent  to  lO.RLB  ORed  with  the  subfunction  bit  TF.RAL. 
The  only  way  to  terminate  an  lO.RAL  function  is  by  a  character  count 
(that  is,  filling  the  input  buffer). 


3.3.2.7  I0.RN2  -  lO.RNE  causes  the  driver  to  read  a  line  from  the 
terminal  without  echoing  the  characters  that  are  input.  This  feature 
is  useful  when  typing  sensitive  information:  for  example,  a  password 
or  combination.   lO.R^tE  is  also  used  to  read  a  badge  with  the  RT02-C. 

(Another  way  to  suppress  echoing  of  input  is  to  set  the  terminal  to 
no-echo  mode  with  the  SP  SMC  QIO  or  the  MCR  SET  /NOECHO  command.  See 
Table  3-5,  bit  TC.NEC.) 

Note  that  the  TC.NEC  subfunction  only  suppresses  echoing  of  solicited 
input.   Unsolicited  input  is  still  echoed. 

CTRL/R,  if  selected  as  a  SYSGEN  option,  is  ignored  while  an  lO.RNE  is 
in  progress. 

lO.RNE  is  equivalent  to  lO.RLB  ORed  with  the  subfunction  bit  TF.RNE. 


3.3.2.8  10. RPR  -  The  QIO  function  10. RPR  (Read  After  Prompt)  has  the 
same  effect  as  lO.WLB  (to  write  a  prompt  to  the  terminal)  followed  by 
10. RLE.  However,  10. RPR  differs  in  four  ways  from  this  combination  of 
QIOs.   With  10. RPR: 

e  System  overhead  is  lower  because  only  one  QIO  is  processed. 

e  There  is  no  "window"  during  which  a  response  to  the  prompt  may 
be  ignored.  Such  a  window  occurs  if  lO.WAL/IO.RLB  is  used, 
because  no  read  may  be  posted  at  the  time  the  response  is 
received . 

e  If  the  issuing  task  is  checkpointable,  it  is  checkpointed 
during  both  the  prompt  and  the  read. 

e  A  CTRL/0  that  may  be  in  effect  is  canceled  before  the  prompt 
is  written. 

The  third  user-specified  argu^nent  to  10. RPR,  tmo,  is  required  for 
compatibility  with  IAS.   If  supplied,  it  is  ignored. 

Subfunction  bits  may  be  ORed  with  10. RPR  to  write  the  prompt  as  a 
Write  All  (TF.BIN)  and  to  send  XOFF  after  the  read  (TF.XOF) .  See  the 
next  two  sections.  In  addition,  the  three  Read  subfunction  bits 
(TF.RAL,  TF.RNE,  TF.RST)  can  be  used  with  10. RPR. 
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3.3.2.9  IO.RPRITF.BIN  -  This  QIO  function  results  in  a  rsad  after  a 
"binary"  pronpt,  that  is,  a  pronpt  that  is  written  by  the  driver  with 
no  character  interpretation  (as  if  it  were  issued  as  an  lO.WAL) . 


3.3.2.10  lO.RPRITP.XOP  -  This  QIO  function  causes  the  driver  to  send 
an  XOFP  to  the  terninal  after  its  pronpt-and-read.  The  XOPP,  or 
CTRL/S,  aay  have  the  effect  of  inhibiting  input  from  the  terninal,  if 
the  terninal  recognizes  XOFf  for  this  purpose. 


3.3.2.11  lO.RST  -  Th  10  function  acts  like  10. RLE,  except  that 
certain  special  characters  terminate  the  read.  These  characters  are 
in  the  ranges  0-37(8)  and  175-177(8).  The  driver  does  not  interpret 
the  terminating  character,  with  certain  exceptions.^  For  example,  a 
horizontal  TAB  (11  octal)  is  not  expanded,  a  RUBOUT  (or  DEL,  177 
octal)  does  not  erase,  and  a  CTRL/C  does  not  get  NCR's  attention. 


Upon  successful  completion 
terminated  by  filliiig  the 
like  the  following: 


of   an   lO.RST  request   that   was   not 
input  buffer,  the  I/O  status  block  looks 


Terminating 
character 


lOSB 


IS.SUCJ.377 


•  of  bytes  in  buffer 


The  terminating  character  is  not  in  the  buffer. 
lO.RST  is  equivalent  to  lO.RLBlTF.RST. 


3.3.2.12  SF.SMC  -  This  QIO  function  allows  a  task  to  set  and  reset 
the  characteristics  of  a  terminal.  Set  Multiple  Characteristics  is 
the  inverse  of  SF.GNC.  Like  SF.GMC,  it  is  called  in  the  following 
way: 

QIO$C  SF.SMC,. . .,<stadd,size> 


stadd 


The  starting  address  of  a  buffer  of  length  "size"  bytes. 

Each  word  in  the  buffer  has  the  form 

.BYTE  characteristic-name 
.BYTE  value 


1.  If  upper-  and  lowercase  conversion  is  disabled  (see  remarks  in 
Section  3.10.9),  the  character  175(8)  echoes  as  right-brace  and  176(8) 
as  tilde,  and  these  characters  do  not  act  as  terminators.  The  three 
characters  CTRL/O,  CTRL/Q,  and  CTRL/S  (17,  21,  and  23(8), 
respectively)  are  not  special  terninators.  The  driver  interprets  then 
as  output  effectors. 
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character 1 at lc-nan« 

One  of  the  symbolic  bit  names  given  in  Table  3-5. 

value 

Either  0  (to  clear  a  given  characteristic)  or  1  (to  set  r 
characteristic) .  Table  3-5  notes  the  restrictions  that  apply  to 
these  characteristics. 

If  characteristic-name  is  TC.TTP  (terminal  type) ,  then  value  can  have 
any  of  the  values  listed  in  Table  3-6. 

A  nonpr ivileged  task  can  only  issue  an  SF.SHC  request  to  affect  its 
own  terminal,  TIO;.  A  privileged  task  can  issue  SF.SMC  to  any 
terminal. 


3.3.2. !3  lO.WAL  -  The  Write  All  function  causes  the  driver  to  pass 
all  output  from  the  buffer  without  interpretation.  It  does  not 
intercept  control  characters.  Lines  are  neither  wrapped  around  (if 
input/output  wrap-around  has  been  selected)  nor  truncated  (if 
wrap-around  is  not  selected)  . 

lO.WAL  is  equivalent  to  lO.WLBi TF.WAL. 


3.3.2.14   lO.WBT  -  The  Write   Break   Through   function   Instructs  the 

driver   to   write   the   buffer   regardless  of   the   I/O  status  of  the 

receiving  terminal.  If  an  lO.WBT  is  issued  on  a  system  that  does  not 
support  lO.WBT,  it  is  treated  as  an  lO.WLB. 

e  If  another  write  is  in  progress,  it  finishes  and  the  lO.WBT  is 
the  next  write  issued.  The  effect  of  this  is  that  lO.WBTs  can 
be  stopped  by  a  CTRL/S.  Therefore,  tasks  may  still  want  to 
time  out  on  lO.WBT. 

e  If  a  read  is  posted,  the  lO.WBT  proceeds  anyway,  and  an 
automatic  CTRL/R  is  performed  to  redisplay  any  input  that  was 
received  before  the  break-through  write. 

•  CTRL/S  and/or  CTRL/0,  if  in  effect,  are  canceled. 

•  Characters  input  during  a  break-through  write  are  ignored. 

An  lO.WBT  cannot  break  through  another  lO.WBT  that  is  in  progress  or 
if  a  prompt  is  being  written  by  10. RPR.  In  either  case,  the  low-order 
byte  of  the  first  word  of  the  I/O  status  block  contains  IE.RSUSr377. 
The  task  receiving  this  error  need  onlv  reissue  the  write. 

Break-through  write  may  only  be  issued  by  a  privileged  task.  However, 
the  task  does  not  have  to  be  mapped  to  the  Executive  (Task  Builder 
options  /PR:4  or  /PR:5).  A  task  can  use  lO.WBT  if  it  is  built  with 
the  /PR:0  switch  specified.  The  privileged  MCR  command  BRO 
(broadcast)  uses  lO.WBT. 

Break-through  write  cannot  break  through  a  multiecho.  Instead,  it 
returns  error  code  lE.RSU.  When  this  occurs,  the  task  should  reissue 
the  write  request. 
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3.4   STATUS  RETURNS 

Table  3-8  lists  error  and  status  conditions  that  are  returned   by   the 
terminal  driver. 

Upon  successful  completion  of  a  read,  the  I/O  status  block  contains 
data  of  this  sort: 


Byte 


Word   0 

1 

ret 

- 

0 

means 

ret 

- 

15 

means 

ret 

- 

33 

means 

ret 

« 

233 

means 

+1 

is 

ret 

+  1 

Number  of  bytes  read 

read  terminated  by  buffer  full 
(byte  count  satisfied); 

IS.CR:   read  terminated  by  carriage  return. 

IS. ESC:  read  terminated  by  an  Altmode. 

IS. ESQ:  read  terminated  by  an  escape  sequence. 

IS.SUC:  the  return  code  for  successful 
completion. 


Most  RSX-llM  return  codes  are  byte  values:  for  example,  IS.SUC  =  1  is 
a  byte  value.  By  contrast,  the  three  return  codes  IS.CR,  IS. ESC,  and 
IS. ESQ  are  word  values.  The  low-order  byte  indicates  successful 
completion,  and  the  high-order  byte  is  required  to  show  what  type  of 
completion  occurred. 

To  test  for  one  of  these  word-value  return  codes,  first  test  the 
low-order  byte  of  the  first  word  of  the  lOSB  for  the  value  IS.SUC. 
Then  test  the  full  word  for  IS.CR,  IS. ESC,  or  IS. ESQ.  (If  the  full 
word  tests  equal  to  IS.SUC,  then  its  high-order  byte  is  0,  indicating 
byte-count  termination  of  the  read.) 

The  "error"  return  IE. EOF  may  be  considered  to  indicate  a  successful 
read,  because  characters  can  be  returned  to  the  task's  buffer. 

The  three  errors  in  Table  3-8  with  SE.xxx  codes  arc  returned  by  thfi 
SP.GMC  and  SF.SMC  QIOs.  They  are  characterized  by  IE.ABOJr377  in  the 
low-order  byte  of  the  first  lOSB  word.  The  high-order  byte  contairis 
the  error  code.  The  second  lOSB  word  contains  an  offset  (starting 
from  0)  to  the  byte  in  error  in  the  QIOs  stadd  buffer. 


3.5   CONTROL  CHARACTERS  AND  SPECIAL  KEYS 

This  section   describes   the   meanings  of  special   terminal   control 

characters   and   keys   for   RSX-llM.    Note  that   the  driver  does  not 

recognize  control  characters   and   special  keys   during   a   Read   All 

requeue   (lO.RAL),  and  recognizes  only  some  of  them  during  a  Read  with 
Special  Term  nators  (lO.RST) . 
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^^F 


# 


Code 


IE. EOF 


IS. sue 


IS.CR 


IS. ESC 


IS. ESQ 


IS.PND 


IE. ABO 


IE. BAD 


Table  3-8 
Terminal  Status  Returns 


Reason 


Successful  completion  on  a  read  with  end-of-fi'\e 

The  line  of  input  read  Trom  the  terminal  was 
terminated  with  the  end-of-file  character  CTRL/Z. 
The  second  word  of  the  I/O  status  block  contains 
the  number  of  bytes  read  before  CTRL/Z  was  seen. 
The  input  buffer  contains  those  bytes. 

Successful  completion 

The  operation  specified  in  the  QIO  directive  was 
completed  successfully.  If  the  operation  involved 
reading  or  writing,  you  can  examine  the  second  word 
of  the  I/O  status  block  to  determine  the  number  of 
bytes  processed.  The  input  buffer  contains  those 
bytes. 

Successful  completion  on  a  read 

The  line  .^f  input  read  from  the  terminal  was 
terminated  by  a  carriage  return.  The  input  buffer 
contains  the  bytes  read. 

Successful  completion  on  a  read 

The  line  of  input  read  from  the  terminal  was 
terminated  by  an  Altmode  character.  The  input 
buffer  contains  the  bytes  read. 

Successful  completion  on  a  read 

The  line  of  input  read  from  the  terminal  was 
terminated  by  an  escape  sequence.  The  input  buffer 
contains  the  bytes  read  and  the  escape  sequence. 

I/O  request  pending 

The  operation  specified  in  the  QIO  directive  has 
not  yet  been  executed.  The  I/O  status  block  is 
filled  with  Os. 

Operation  aborted 

The  specified  I/O  operation  was  canceled  by  lO.KIL 
while  in  progress  or  while  in  the  I/O  queue.  The 
second  word  of  the  lOSB  shows  how  many  bytes  were 
processed  before  the  kill  took  effect.  Note  that 
the  SE,xxx  error  codes  are  characterized  by  IE.ABO& 
377  in  the  low-order  byte  of  the  first  word  of  the 
lOSB. 

Bad  parameter 

The  size  of  the  prompt  in  a  read-after-proinpt  QIO 
is  too  big  (that  is,  greater  than  255  bytes  on 
systems  supporting  variable-length  buffers  or 
greater  than  80  on  systems  that  do  not) . 


(continued  on  next  page) 
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Table  3-8   (Cont.) 
Terminal  Status  Returns 


Code 

Reason 

lE.DAA 

Device  already  attached 

The  physical  device  unit  specified   in  an   10. ATT 

function  was  already  attached  by  the  issuing  task. 

This  code   indicates  that  the   issuing   task  has 

already  attached  the  desired  physical  device  unit, 

not  that  the  unit  was  attached  by  another  task.   If 

the   attach   specified   TP.AST  or   TF.ESQ,   these 

subfunction  bits  have  no  effect. 

le.DNA 

Device  not  attached 

The  physical  device  unit  specified   in  an   lO.DET 

function  was  not  attached   by  the  issuing  task. 

This  code  has  no  bearing  on  the  attachment  status 

of  other  tasks. 

lE.DNR 

Device  not  ready 

The  physical   device  unit  specified   in   the  QIO 

directive  was  not  ready  to  perform  the  desired  I/O 

operation.   This  code  is  returned  to   indicate  one 

of  the  following  conditions: 

e  A  time-out  occurred  on  the  physical  device  unit 

(that  is,  an  interrupt  was  lost). 

e  An  attempt  was  made  to  perform  a  function  on  a 

u 

remote   DHll   or   DZll   line  without  carrier 

present.   (The  line  is  hung  up.) 

■ 

lE.IES 

Invalid  escape  sequence 

An  escape  sequence  was  started  but  escape-sequence 

syntax   was   violated   before   the  sequence  was 

completed.   See  Section  3.6.4. 

IE. IPC 

Illegal  function 

A  function  code  specified  in  an   I/O  request  was 

Illegal   for   terminals;   or,   the   function  code 

specified  was  a  SYSGEN  option  not  selected  for  this 

system. 

IE. NOD 

Buffer  allocation  failure 

System  dynamic  storage  has  been  depleted,  and  there 

was   insufficient  space  available   to  allocate  an 

intermediate  buffer  for  an  input  request. 

(continued  on  next  page) 
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Table  3-8   (Cont.) 
Terminal  Status  Returns 


Code 


lE.OPL 


IE. PES 


lE.PRI 


lE.RSU 


lE.SPC 


SE.BIN 


SE.NIH 


SE.VAL 


Reason 


Device  off  line 

The  physical  device  unit  associated  with  the  LUN 
specified  in  the  QIO  directive  was  not  on  line. 
When  the  system  was  booted,  a  device  check 
indicated  that  this  physical  device  unit  was  not  in 
the  configuration. 

Partial  escape  sequence 

An  escape  sequence  was  started,  but  read-buffer 
space  was  exhausted  before  the  sequence  was 
completed.   See  Section  3.6.4.3. 

Privilege  violation 

In  a  multiuser  system,  a  nonprivileged  task  either 
issued  an  lO.WBT  or  directed  an  SF.SMC  to  a 
terminal  other  than  its  own  TIO:. 

Resource  in  use 

The  prompt  of  an  10. RPR,  or  a  break-through  write, 
was  in  progress  when  an  lO.WBT  was  issued.  Reissue 
the  10. WET  later. 

Illegal  address  space 

The  buffer  specified  for  a  read  or  write  request 
was  partially  or  totally  outside  the  address  space 
of  the  issuing  task.  Alternately,  a  byte  count  of 
0  was  specified. 

The  new  value  specified  for  a  terminal 
characteristic  in  an  SF.SMC  request  was  not  0  or  1. 
(Characteristics  other  than  TC.TTP  —  see  Table 
3-5.) 

A  terminal  characteristic  other  than  those  in  Table 
3-5  was  named  in  an  SF.GMC  or  SF.SMC  request;  or, 
a  task  attempted  to  assert  TC.PRI. 

The  new  value  specified  in  an  SF.SMC  request  for 
the  TC.TTP  terminal  characteristic  was  not  one  of 
those  listed  in  Table  3-6,  or  the  baud  rate  (speed) 
specified  is  not  valid. 
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3.5.1  Control  Charactors 


A  control  character  is  input  from  a  terminal  by  holding  the  control 
key  (CTRL)  down  while  typing  one  other  key.  Two  of  the  control 
characters  described  in  Table  3-9,  CTRL/U  and  CTRL/Z,  are  echoed  on 
the  terminal  as  "U  and  'Z,  respectively.  Other  control  characters  are 
recognized  by  the  terminal  driver,  but  are  not  printing  characters  and 
therefore  are  not  echoed. 


Table  3-9 
Terminal  Control  Characters 


Character 


CTRL/C 


CTRL/ I 

CTRL/ J 
CTRL/K 

CTRL/L 

CTRL/M 


Meaning 


Typing  CTRL/C  repeatedly  is  the  way  to  get  a 
terminal's  attention.  Normally,  typing  CTRL/C 
causes  unsolicited  input  on  that  terminal  to  be 
directed  to  the  Monitor  Control  Routine  (MCR) . 
"MCR>"  echoes  when  the  terminal  is  ready  to  accept 
unsolicited  input.  When  the  unsolicited  input 
completes,  it  is  passed  to  MCR. 

If  the  last  item  typed  on  the  terminal  was  CTRL/S 
(suspend  output) ,  then  CTRL/C  restarts  suspended 
output  and  directs  subsequent  input  to  MCR. 

If  the  hold-screen  mode  option  has  been  selected  at 
SYSGEN,  and  if  the  terminal  is  a  VT5x  or  VT61  in 
hold-screen  mode,  then  typing  a  string  of  CTRL/Cs 
eventually  removes  the  terminal  from  hold-screen 
mode. 

Not  all  CTRL/Cs  act  to  get  MCR's  attention. 
CTRL/Cs  are  directed  to  a  task  if  the  task  has 
attached  a  terminal  and  has  specified  an 
unsolicited-input-character  AST.  See  the  discussion 
on  unsolicited-input-character  ASTs,  Section 
3.3.2.1.  CTRL/Cs  also  go  to  a  task  if  an  lO.RAL 
(Read  All)  or  lO.RST  (Read  with  Special 
Terminators)  is  posted. 

Typing  CTPL/I  or  TAB  initiates  a  horizontal  tab, 
and  the  terminal  spaces  to  the  next  tab  stop.  Tabs 
at  every  eighth  character  position  are  simulated  by 
the  terminal  driver. 

Typing  CTRL/J  is  equivalent  to  typing  the  LINE  FEED 
key  on  the  terminal. 

Typing  CTRL/K  initiates  a  vertical  tab,  and  the 
terminal  performs  four  line  feeds. 


Typing  CTRL/L  initiates  a  form  feed,  and  the 
terminal  performs  eight  line  feeds.  Paging  is  not 
performed. 

Typing  CTRL/M  is  equivalent  to  typing  the  carriage 
RETURN  key  on  the  terminal  (see  Section  3.5.2). 


(continued  on  next  page) 
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Table  3-9   (Cont.) 
Terminal  Control  Characters 


Character 


Meaning 


CTRL/0 


CTRL/Q 
CTRL/R 


CTRL/S 


CTRL/U 


CTRL/Z 


Typing  CTRL/0  suppresses  output  being  sent  to  a 
terminal  by  the  current  I/O  request.  For  attached 
terminals,  CTRL/0  remains  in  effect,  and  output 
continues  to  be  suppressed  until  any  of  the 
following  occurs: 

1.  The  terminal  is  detached. 

2.  Input  is  entered. 

3.  Another  CTRL/0  character  is  typed. 

4.  An  10. ceo,  lO.WBT,  or  10. RPR  is  processed. 

For  unattached  terminals,  CTRL/0  suppresses  output 
for  only  the  current  output  buffer  (aenerally  one 
line). 

(SYSGEN  option.)  Typing  CTRL/Q  resumes  terminal 
output  previously  suspended  by  means  of  CTRL/S. 

(SYSGEN  option.)  Typing  CTRL/R  on  a  terminal 
results  in  the  echo  of  CR/LF  followed  by  the 
incomplete  (unprocessed)  input  line.  Any  tabs  that 
were  input  are  expanded  and  the  effect  of  any 
rubouts  is  shown.  On  hard-copy  terminals,  CTRL/R 
allows  you  to  verify  the  effect  of  tabs  and/or 
rubouts  in  an  input  line.  CTRL/R  is  also  useful 
for  CRT  terminals  when  the  automatic-cariage-return 
and  CRT  rubout  SYSGEN  options  have  been  selected 
(see  Section  3.8).  For  example,  after  rubbing  out 
the  leftmost  character  on  the  second  displayed  line 
of  a  wrapped  input  line,  you  will  find  that  the 
cursor  does  not  move  to  the  right  of  the  first 
displayed  line.  In  this  case,  CTRL/R  brings  the 
input  line  and  the  cursor  back  together  again. 

(SYSGEN  option.)  Typing  CTRL/S  causes  terminal 
output  to  be  suspended.  Output  is  resumed  by 
typing  CTRL/Q  or  CTRL/C. 

Typing  CTRL/U  before  typing  a  line  terminator 
causes  previously  typed  characters  to  be  deleted 
back  to  the  beginning  of  the  line.  The  system 
echoes  this  character  as  *U  followed  by  a  carriage 
return  and  a  line  feed.  This  allows  you  to  retype 
the  line. 


Typing  CTRL/Z  indicates 
current  terminal  input, 
and  other  system  tasks 
complete  and  the  task 
echoes  this  character  as 
return  and  a  line  feed. 


an  end-of-flle  for  the 
It  signals  MAC,  PIP,  TKB, 
that  terminal  input  is 
should  exit.  The  system 
*Z  followed  by  a  carriage 
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3.5.2  Spacial  Rays 

The  Escape,  carriage  RETURN,  and  RUBOUT  keys  have  special  significance 
for  terminal  input,  as  described  in  Table  3-10.  A  line  can  be 
terminated  by  an  ESCape  (or  Altmode)  character,  by  a  carriage  RETURN, 
by  CTRL/Z,  or  by  completely  filling  the  input  buffer  (that  is,  by 
exhausting  the  byte  count  before  a  line  terminator  is  typed).  The 
standard  buffer  size  for  a  terminal  can  be  determined  by  issuing  a  GET 
LUN  INFORMATION  system  directive  and  examining  Word  5  of  the 
in^'ormation  buffer.  Another  way  is  to  type  the  MCR  command  "SET 
/BUP-TI:". 


3.6   ESCAPE  SEQUE3ICES 

Escape  sequences  are  strings  of  two  or  more  characters  beginning  with 
33  octal.  Some  terminals  generate  an  escape  sequence  when  a  special 
key  is  pressed  (for  example,  the  PFl  key  on  the  VTIOO) .  On  any 
terminal,  an  escape  sequence  may  be  generated  manually  by  typing 
Escape  and  the  appropriate  following  characters. 

Escape  sequences  provide  a  way  to  pass  input  to  a  task  without 
interpretation  by  the  operating  system.  This  could  be  done  with  a 
number  of  1-character  Read  Alls,  but  escape  sequences  allow  a  neater 
way  to  accomplish  it  (they  can  be  read  with  ordinary  lO.RLBs). 

Most  DIGITAL  software  currently  does  not  employ  escape  sequences.  The 
specifics  provi"^  '  here  are  for  the  benefit  of  users  who  wish  to  take 
advantage  of  escape  sequences  in  their  own  tasks. 


3.6.1  Definition 

An  escape  sequence  i*;  defined  as  follows: 
ESC  [int]  ...  [Int]  fin 


ESC 


The  result  of  pressing  the  ESCape  key,  ^^  byte  (character)  of 
33(8). 

int 

An  "intermediate  character"  in  the  range  40(8)  to  57(8).  This 
range  Includes  the  character  "space"  and  15  punctuation  marks. 
An  escape  sequence  may  contain  any  number  of  Intermediate 
characters,  or  none. 

fin 

A  "final  character"  in  the  range  60(8)  to  176(8).  This  range 
includes  upper-  and  lowercase  letters,  numbers,  and  .13 
punctuation  marks. 

There  are  four  exceptions  to   this  general  definition  discussed   in 
Section  3.6.5. 
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Table  3-10 
Special  Teriainal  Kays 


Key 


Meaning 


Escape 


If  escape  sequences  are  not  recognized,  typing 
Escape  or  Altnode  signals  the  terninal  driver  that 
there  is  no  further  input  on  the  current  line. 
This  line  terminator  allows  further  input  on  the 
saae  line,  because  the  carriage  or  cursor  is  not 
returned  to  the  first  column  position. 

If  escape  sequences  are  recognized,  ESCape  signals 
the  beginning  of  an  escape  sequence.  See  Section 
3.*5. 


RETURN 


Typing  RETURN  terminates  the  current  line  and 
causes  the  carriage  or  cursor  to  return  to  the 
first  column  on  the  line. 


RUBOUT 


Typing  RUBOUT  deletes  the  last  character  typed  on 
an  input  line.  Only  characters  typed  since  the 
last  line  terminator  may  be  deleted.  Several 
characters  can  be  deleted  in  sequence  by  typing 
success  i  ve  RUBOUTs . 


The  first  RUBOUT  echoes  as  a  backslash  (\) , 
followed  by  the  character  that  has  been  deleted. 
Subsequent  RUBOUTs  cause  only  the  deleted  character 
to  be  echoec^.  The  next  character  typed  that  is  not 
a  RUBOUT  causes  another  backslash,  followed  by  the 
new  character,  to  be  echoed.  The  following  example 
illustrates  rubbing  out  ABC  and  then  typing  CBA: 

ABC\CBA\CBA 

The  second  backslash  is  not  displayed  if  a  line 
terminator  is  typed  after  rubbing  out  the 
characters  on  a  line,  as  in  the  following: 

ABCNCBA 

(SYSGEN  option.)  At  SYSGEN  time  you  may  elect  to 
support  a  "CRT  rubout"  feature.  This  feature 
applies  to  a  terminal  only  after  a  SET  MCR 
directive  has  been  issued: 


SET  /CRT-TIi 


(Note 
SET  ca 
f unctio 
charact 
input  1 
If  the 
backspa 
charact 
1 ong  i  n 
automat 
erases 
cursor 
must  be 
content 


See  Sec 
n   be   a 
n.)  When 
er   (if 
ine  and 

last 
ces  are 
er  posi 
put  line 
Ic-carr i 
the  last 
is  not 
used  to 
s  of  the 


tion  3.3.2.12  for 
ccomplished,  with 
a  RUBOUT  is  struc 
any)  is  removed  f 
backspace-space-ba 
typed  character 
issued  to  move  th 
tion  before  the  ta 

was  «-plit  .  or 
age-return  optlo 
character  of  a  pr 
movea  to  the  prev 
resynchronize  the 
incomplete  input 


another  way  this 
the  SP.SMC  010 
k,  the  last  typed 
rom  the  incomplete 
ckspace  is  echoed. 
was  c  tab,  enough 
e  cursor  to  the 
b  was  typed.  If  a 
wrapped,"  by  the 
n,  and  a  RUEOUT 
evious  line,  the 
ious  line.  CTRL/R 
display  with  the 
line. 
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3. A. 2  Pr«r«quisit«s 

Two  prerequisites  must  be  satisfied  before  escape  sequences  can  be 
received  by  a  task. 

First,  the  task  must  "ask"  for  them  by  issuing  an  10. ATT  and  invoking 
the  subf unction  bit  TP.ESQ. 

Second,  the  terminal  must  be  declared  capable  of  generating  escape 
sequences.   This  may  be  done  with  an  NCR  SET  command: 

SET  /E3CSE0-TI: 

An  alternative  way  to  tell  the  driver  that  the  terminal  can  generate 
escape  sequences  is  by  issuing  the  Set  Multiple  Characteristics  QIO. 
See  Section  3.3.2.13. 

If  either  of  these  prerequisites  is  not  satisfied,  the  ESC  character 
is  treated  as  a  line  terminator.  If  both  prerequisites  are  satisfied, 
then  an  additional  feature  results.  CTRL/SHIFT/0  (37(8))  may  be  used 
as  an  Altmode.  *■ 

Thl3  choracter  does  not  act  as  an  Altmode  from  a  terminal  that  cannot 
generate  escape  sequences. 


3.^.3  Characteristics 

Escape  sequences  always  act  as  line  terminators.  That  is,  an  input 
buffer  may  contain  ot  ler  characters  that  are  not  part  of  an  escape 
sequence,  but  an  escapv.'  sequence  always  comprises  the  last  characters 
in  the  buffer. 

Escfiue  sequences  are  not  echoed.  However,  if  a  non-CRT  rubout 
sequence  is  in  progress,  it  is  closed  with  a  backslash  when  an  escape 
sequence  is  begun. 

Escape  sequences  are  not  recognized  in  unsolicited  input  streams. 
Neither  are  they  recognized  in  a  Read  with  Special  Terminators 
(subfunction  bit  TF.RST)  nor  in  a  Read  All  (subfunction  bit  TF.RAL). 


3.6.4   Escape  Sequence  Syntax  Violations 

A  violation  of  the  syntax  defined  in  Section  3.6.1  causes  the  driver 
to  abandon  the  escape  sequence  and  to  return  an  error  (lE.IES). 


3.6.4.1  DEL  or  RUBOUT  (177(8))  -  The  character  DEL  or  RUBOUT  is  not 
legal  within  an  escape  sequence.  Typing  it  at  any  point  within  an 
escape  sequence  causes  the  entire  sequence  to  be  abandoned  and  deleted 


1.  An  Altmode  is  a  line  terminator  that  does  not  cause  the  cursor  to 
advance  to  a  new  line.  On  terminals  that  cannot  generate  escape 
sequences,  the  ESCape  key  acts  as  an  Altmode.  So  do  the  characters 
175(8)  and  176(8),  if  the  terminal  has  not  been  declared  lowercase 
(MCR  command  SET  /LOWER).  If  the  terminal  is  lowercase,  then  these 
characters  represent  right-brace  and  tilde,  respectively. 
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from  the  input  buffer.  Thus,  use  DEL  or  RUBOUT  to  abandon  an  escape 
sequence,  if  desired,  once  you  have  begun  it.  For  example,  if  you 
enter: 

AB  ESC  "  DEL  CR 

the  buffer  contains  "AB"  and  the  I/O  status  block  looks  like  the 
following: 


lOSB 


IS.CR 


3.6.4.2  Control  Characters  (0-37(8))  -  The  reception  of  any  character 
in  the  range  0  to  37(8)  (with  four  exceptions  —  see  footnote^)  is  a 
syntax  violation  that  terminates  the  read  with  an  error  (lE.IES).  For 
example,  entering: 


ESC  1   CTRL/SHIFT/0 

results  in  a  buffer  that  contains  these  three  characters  and 
status  block  that  is  similar  to  the  following: 


an 


lOSB 


IE. IBS 


I/O 


3.6.4.3  Full  Buffer  -  A  syntax  error  results  when  an  escape  sequence 
is  terminated  by  running  out  of  read-buffer  space,  rather  than  by 
reception  of  a  final  character.  The  error  IE. PES  is  returned.  For 
example,  after  a  task  issues  an  lO.RLB  QIO  with  a  buffer  length  of  2, 
and  you  type: 

ESC  I   A 

the  buffer  contains  "ESC  !",  and  the  I/O  status  block  contains: 


lOSB 


IE. PES 


The  "A"  is  treated  as  unsolicited  input, 


1.  Four  control  characters  are  allowed:  CTRL/Q,  CTRL/S,  CTRL/C,  and 
CTRL/O.  These  characters  are  handled  normally  by  the  operating  system 
even  when  an  escape  sequence  is  in  progress.   For  example,  entering: 

ESC  CTRL/S  A 


gives: 


lOSB 


IS. ESQ 


with  the  side  effect  of  turning  off  the  output  stream. 
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3.6.5  Exc*ptlon«  to  Escap«-S«qu«nc«  Syntax 

Pour  "final  characters"  that  noraally  would  terminate  an  escape 
sequence  are  treated  as  special  cases  by  the  terminal  driver.  These 
special  cases  exist  for  historical  compatibility  reasons.  Three  of 
these  characters  are:  ;  (73(8)),  ?  (77(8)),  and  0  (117(8)).  The 
syntax  for  escape  sequences  that  contain  these  four  characters  as 
intermediates  is: 


ESC  ;  [inti 
ESC  ?  [int] 
ESC  0  Tint] 


int 
fin 

finl 


•  > 
-> 
«> 


40-57 
60-176 
100-176 


[int]  fin 

tint]  fin 

[int]  finl 

(8). 
(8). 
(8). 


The  fourth  exception  to  the  general  syntax  given  in  Section  3.6.1 
involves  the  "final  character"  Y  (131(8)).  Historically  (for  example, 
in  the  VT52) ,  ESC  Y  has  been  used  to  signal  the  cursor  position.  It 
is  followed  by  two  numbers  signifying  column  and  row  positions: 

ESC  Y  colpos  rowpos 

where  colpos  and  rowpos  are  both  characters  in  the  range  40-176(8). 
They  represent  bias-40  numbers:  colpos  *  40  corresponds  to  column  0, 
and  so  forth. 


1.7   VERTICAL  FORMAT  CONTROL 

Table  3-11  summarizes  the  meanings  of  all  characters  used  for  vertical 
format  control  on  the  terminal.  Any  one  of  these  characters  can  be 
specified  as  the  value  of  the  vfc  parameter  in  the  functions  lO.WLB, 
lO.WVB,  lO.WBT,  lO.CCO,  or  10. RPR. 


Table  3-11 
Vertical  Format  Control  Characters 


Octal 
Value 

Character 

Meaning 

40 
60 

61 

blank 
0 

1 

SINGLE  SPACE  -  Output  a  line  feed,   print   the 
contents  of  the  buffer,  and  output  a  carriage 
return.    Normally,   printing    immediately 
follows  the  previously  printed  line. 

DOUBLE  SPACE  -  Output  two   line   feeds,   print 
the  contents  of  the  buffer,  and  output  a 
carriage   return.    Normally,   the   buffer 
contents  are  printed  two  lines  below  the 
previously  printed  line. 

PAGE  EJECT  -  Output  eight  line  feeds   (or,   if 
the  terminal   is  an  LA180S,  output  a  form 
feed),  print  the  contents  of  the  buffer,  and 
output  a  carriage  return. 

(continued  on  next  page) 
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Table  3-11   (Cont.) 
Vortical  Format  Control  Characters 


Octal 
Value 

Character 

Meaning 

53 
44 

00 

+ 
$ 

null 

OVERPRINT  -  Print  the  contents  of  the  buffer 
and   output   a   carriage  return,   normally 
overprinting  the  previous  line. 

PROMPTING  OUTPUT  -  Output  a  line   feed   and 
print   the   contents  of  the  buffer.   This  mode 
of  output  is  intended  for  use  with  a  terminal 
on  which  a  prompting  message  is  output,  and 
input  is  then  read  on  the  same  line. 

INTERNAL  VERTICAL  FORMAT  -  Print   the   buffer 
contents  without   addition  of  vertical  format 
control  characters.   In  this  mode,  more  than 
one  line  of  guaranteed  contiguous  output  can 
be  printed  for  each  I/O  request. 

All  other  vertical  format  control  characters  are  interpreted  as  blanks 
(40(8)). 


3.8   FEATURES  AVAILABLE  BY  SYSGEN  OPTION 

A  number  of  terminal-driver  features  are  available  as  options  at  the 
time  the  RSX-llM  system  Is  generated  (see  the  RSX-llM  System 
Generation  and  Management  Guide  or  RSX-llS  System  Generation  an"? 
Installation  Guide,  as  appropriate) .  Some  that  have  been  mentioned 
previously  in  the  text  are: 

•  All  the  device-specific  QIO  functions 

•  Special  keys 

CTRL/S  —  Suspend  output 
CTRL/Q  —  Resume  suspended  output 
-  CTRL/R  —  Write  incomplete  input  buffer 
CRT  rubout 

•  Escape  sequences 

Other  features  that  you  may  select  at  SYSGEN  time  are  described  in  the 
following  sections. 


3.8.1  Automatic  Carriage  Return 

By  SYSGEN  option,  all  terminals  in  a  system  may  be  set  to  "wrap 
around,"  on  input  and  output,  after  a  specified  number  of  columns.  If 
this  option  is  selected,  the  number  of  characters  per  line  is 
determined  on  a  terminal-by-terminal  basis.  An  MCR  SET  command  is 
used  to  specify  the  wrap-around  column,  n: 

>SET  /BUF-TI:n 
> 
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(Note  that  n  is  an  octal  number  by  default.  Type  an  explicit  decimal 
point  to  enter  a  decimal  number.)  After  SYSGEN  and  before  this  SET  has 
been  done  for  a  given  terminal,  the  default  column  width  is  72 
(decimal) . 

The  SET  /BUF  command  used  without  an  argument  is  an  enquiry  that 
returns  the  current  buffer  width  for  a  terminal: 

>SET  /BUF-Tl! 

BUF-TI0:00072. 

> 

A  task  can  determine  the  buffer  width  by  issuing  a  Get  LUN  Information 
directive  and  examining  word  5. 

After  the  SET  has  been  done,  typing  the  n+lst  character  results  in  a 
CP/LF  being  output  before  the  n+lst  character  is  echoed  (at  the 
leftmost  character  position  of  the  next  line).  There  is  still  only 
one  input  line,  but  it  is  displayed  on  two  lines  on  the  terminal. 

Output  also  wraps  around  after  column  n.  This  is  undesirable  for  some 
applications.  To  disable  wrap-around,  set  the  buffer  to  some  number 
greater  than  the  terminal's  column  width.  Output  —  and  Input 
too  —  beyond  the  column  width  will  then  overprint  at  the  right 
margin.  Wrap-around  is  also  disabled  when  executing  the  lO.WAL 
function  (see  Section  3.10.11),  because  the  driver  does  not  keep  track 
of  the  cursor's  position. 

It  is  possible  to  lose  track  of  whore  you  are  in  the  input  buffer  if 
both  the  automatic  carriage  return  and  the  CRT  rubout  features  have 
been  selected  at  SYSGEN.  If,  while  rubbing  out  text  on  a  wrapped 
line,  you  rub  out  the  first  character  on  that  line,  the  cursor  will 
not  back  up  to  the  previous  line.  In  order  to  resynchroni ze  the 
cursor  with  the  contents  of  the  Incomplete  input  buffer,  type  CTRL/R 
(if  this  option  has  been  selected). 

It  is  also  possible  to  cause  wrap-around  to  malfunction.  This  can 
occur  when  more  than  255(10)  characters  are  output  without  an 
intervening  carriage  return.  This  condition  is  possible  because  the 
driver  maintains  a  byte  location  with  the  current  cursor  position; 
thus,  counts  greater  than  255(10)  are  truncated,  and  the  cursor  count 
will  be  invalid  until  the  next  carriage  return  is  received. 


3.8.2  Variable-Length  Buffering 

If  this  user-transparent  SYSGEN  option  is  selected,  up  to  255(10) 
characters  may  be  read  from  a  terminal.  The  terminal  driver  allocates 
an  Executive  buffer  the  same  size  as  the  read  request. 

If  the  variable-length  option  is  not  chosen,  any  number  of  characters 
may  be  re/ ^  from  a  terminal,  but  a  maximum  of  80(10)  are  transferred 
to  the  task  Issuing  the  read  request.  An  Executive  buffer  of  80(10) 
characters  is  always  allocated. 

Note  that,  whether  variable-length  buffering  is  selected  or  not,  a 
maximum  of  80(10)  characters  may  be  directed  to  MCR  as  unsolicited 
input. 
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3.8.3  Task  Buffering  of  Received  Characters 

This  user-transparent  SYSGEN  option  causes  characters  read  from  the 
terminal  to  be  sent  directly  to  the  reading  task's  buffer.  With  this 
option,  no  Executive  buffer  need  be  allocated,  and  the  completed  input 
line  need  not  be  transferred  to  the  task's  buffer.  This  option, 
however,  does  not  necessarily  reduce  system  overhead.  In  a  mapped 
system,  each  character  must  oe  mapped  to  the  task's  buffer.  If 
Executive  buffering  was  used,  the  mapping  is  done  once  and  then  all 
the  characters  are  transferred.  For  the  half-duplex  terminal  driver, 
the  Executive  buffers  only  input  except  for  the  prompt  output  on  an 
10. RPR  request. 

Task  buffering  may  be  overridden  by  checkpointing.  If  a  task  is 
checkpointable,  an  Executive  buffer  is  allocated  in  the  normal  way  and 
the  task  is  made  eligible  for  checkpointing  by  any  task,  regardless  of 
priority,  while  the  read  proceeds.  (Checkpointing  only  occurs  when 
there  is  another  task  that  can  be  ir.ade  active.)  Since 
checkpointability  is  a  dynamic  quality  controlled  by  the  task,  the 
user  retains  control  over  the  resource  trade-off. 


3.8.4   LA30-P  Support 

This  option  provides  a  ^ -byte  software  buffer  for  terminal  input  from 
an  LA30-P.  Because  LA3n-Ps  communicate  with  RSX-llM  by  a 
single-buffered  hardware  interface,  the  echoing  of  an  input  character 
may  block  the  reception  of  the  next  input  character.  This  is  because 
a  character  is  normally  discarded  by  the  terminal  driver  if  it  is 
received  before  the  echo  of  the  previous  character  completes.  The 
SYSGEN  option  for  LA30-P  support  (transparent  to  the  user)  will  buffer 
the  second  character  in  the  software. 

This  option  should  not  be  chosen  at  SYSGEN  if  there  are  no  LA30-Ps  in 
the  system. 


3.9   TERMINAL  INTERFACES 

This  section  summarizes  the  characteristics  of  the  four  types  of 
standard  communication-line  interfaces  supported  by  RSX-llM.  All  four 
interfaces  support  parity,  but  RSX-llM  does  not. 


3.9.1   DHll  Asynchronous  Serial  Line  Multiplexer 

The  DHll  multiplexer  interfaces  up  to  16  asynchronous  serial 
communications  lines  for  terminal  use.  The  DHll  supports  programmable 
baud  rates.  Input  and  output  baud  rates  may  differ;  the  input  rate 
may  be  set  to  0  baud,  thus  effectively  turning  off  the  terminal.  The 
DMll-BB  option  may  be  included  '.o  provide  modem  control  for  dial-in 
lines.  These  lines  must  be  interfaced  by  means  of  a  full  duplex  modem 
(for  example,  in  the  United  States,  a  Bell  103A  or  equiv3lent  modem). 

The  direct  memory  access  (DMA)  capability  of  the  DHll  is  not  supported 
by  the  RSX-llM  terminal  driver. 
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3.9.2  DJll  Asynchronous  Ssrlal  Lin*  Multiplsxsr 

The  DJll  multiplexer  interfaces  as  many  as  16  asynchronous  serial 
lines  to  the  PDP-11  for  local  terminal  communications.  The  DJll  does 
not  provide  a  dial-in  capability,  but  supports  jumper-selectable  baud 
rates. 


3.9.3  DLll  Asynchronous  Serial  Lin*  Interfac* 

The  DLll  supports  a  single  asynchronous  serial  line  and  handles 
communication  between  the  PDP-11  and  a  terminal.  A  number  of  standard 
baud  rates  are  available  to  DLll  users.  Pour  versions  of  the  DLll 
interface  are  supported  by  RSX-llM  for  terminal  use:  DLll-A,  DLll-B, 
DLll-C,  and  DLll-D.  The  DLll-E  is  supported  by  the  full-duplex 
terminal  driver  described  in  Chapter  2,  and  by  the  message-oriented 
communication  drivers  described  in  Chapter  11. 


3.9.4  DZll  Asynchronous  Serial  Line  Multiplexer 

The  DZll  multiplexer  interfaces  up  to  eight  asynchronous  serial 
communication  lines  for  use  with  terminals.  It  supports  programmable 
baud  rates;  however,  input  and  output  speeds  must  be  the  same.  The 
DZll  can  control  a  full  duplex  modem  in  auto-answer  mode. 


3.10   PROGRAMMING  HINTS 

This  section  contains  information  relevant  to  users  of  the  terminal 
driver. 


3.10.1  Terminal  Line  Truncation 

If  automatic  carriage  return  has  not  been  selected  at  SYSGEN,  and  if 
the  number  of  characters  to  be  printed  exceeds  the  line  length  of  the 
physical  device  unit,  then  the  terminal  driver  discards  the  excess 
characters  until  it  receives  one  that  instructs  it  to  return  to 
horizontal  position  1.  You  can  determine  when  this  will  happen  by 
examining  word  5  of  the  information  buffer  returned  by  the  Get  LUN 
Information  system  directive,  or  by  typing  "SET  /BUF=TI:". 


e 


3.10.2  Escape  Code  Conversion 

If  escape  sequences  are  not  recognized,  an  ESCape  or  Altmode  character 
code  of  33,  175,  or  176  is  converted  internally  to  33  before  it  is 
returned  to  the  user  on  input.     »         -    * 


3.10.3  RT02-C  Control  Function    '• 

Because  the  screen  of  an  RT02C  Ba'ige  Reacier  and  Data  Entry  Term^nwl 
holds  only  one  line  of  information,  special  caro  must  be  taken  when 
sending  a  control  character  (for  example,  vertical  ta?- '  to  the  RT02-C. 
Use  lO.WAL  (Write  All)  . 


• 
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It  Is  advisable  to  read  without  echoing  when  reading  a  badge  with  the 
RT02-C.  Use  lO.RAL  or  lO.RNE,  and  then  write  the  received 
information. 

3.10.4  Checkpointing  During  Terminal  Input 

If  checkpointing  during  terminal  input  was  selected  as  a  SYSGEN 
option,  a  checkpointable  task  is  stopped  (and  therefore  eligible  to  be 
checkpointed)  when  trying  to  read.  Therefore,  a  stratagem  such  as 
issuing  a  read  followed  by  a  mark-time  does  not  work.  The  intent 
might  be  to  time  out  the  read  if  input  is  not  received  in  a  reasonable 
length  of  time.  But  the  mark-time  is  not  issued  until  the  read 
completes. 

You  can  circumvent  this  behavior  by  disabling  checkpointing  for  the 
read.  This  's  not  a  desirable  solution  because  It  forces  a  task  to 
remain  in  memory  during  the  entire  read.  This  defeats  the  puipose  of 
selecting  the  checkpoint-during-teiminal-input  option. 


3.10.5  Time  Required  for  lO.KIL 

An  lO.KIL  request  may  take  up  to  1  second  to  succeed,  . ecause  an 
internal  mark-time  mechanism  is  used  to  generate  a  software  interrupt 
to  get  into  a  clean  state.  The  I/O  may  reach  a  state  in  which  the 
kill  can  complete  within  this  time  (for  instance,  if  a  hardware 
interrupt  is  received).   If  not,  the  request  is  killed  after  1  second. 


3.10.6   Use  of  lO.WVB 

We  recommend  that  you  routinely  use  lO.WVB,  instead  of  lO.WLB,  when 
writing  to  a  terminal.  If  the  write  actually  goes  to  a  terminal,  the 
Executive  converts  your  lO.WVB  into  lO.WLB.  However,  if  the  LUN  has 
been  redirected  to  some  inappropriate  device  —  a  disk,  for 
example  —  using  an  lO.WVB  will  be  rejected  because  a  file  is  not  open 
on  the  LUN.  This  prevents  privileged  tasks  from  overwriting  block 
zero  of  the  disk  (the  boot  block) . 

Note  that  any  subfunction  bits  specified  in  the  lO.WVB  request  (for 
example,  TF.CCO,  TF.WAL,  or  TF.WBT)  are  stripped  off  when  the  QIO  is 
converted  to  an  lO.WLB. 


3.10.7  Remote  DHll  and  DZll  Lines 

All  remote  DHll  lines  in  a  system  are  answered  at  the  same  baud  rate. 
All  remote  DZll  lines  are  also  answered  at  the  same  rate,  which  may 
differ  from  the  DHll  rate.  These  rates  are  specified  at  system 
generation. 

Before  a  remote  DHll  or  DZll  line  is  answered,  the  driver  clears 
certain  of  the  terminal  characteristics  (see  Table  3-5)  that  may  have 
been  set  by  an  MCR  SET  command  or  by  an  SF.SMC  QIO.  The 
characteristics  cleared  are:  TC.SCP,  TC.ESQ,  TC.HLD,  TC.SMR,  and 
TC.TTP.  (Clearing  TC.TTP  m.-ans  that  a  terminal  type  of  "unknown"  is 
returned  to  an  SF.GMC  request.)  Also,  buffer  size  is  set  to  73. 


3-31 


■■•"-  ■^—  ■  •- 


HALF-DUPLEX  TERMINAL  DRIVER 

A  DZll  remote  line  must  be  declared  to  be  remote  before  the  terminal 
driver  will  correctly  handle  the  modem.  This  is  done  with  the  MCR 
command  SET  /REMOTE-TI:. 

NOTE 

Because  of  the  few  modem  signals  that 
the  DZll  handles  and  the  lack  of 
interrupt  support  provided  for  those 
signals,  the  DZll  may  not  adequately 
handle  telephone  exchange  requirements 
in  all  countries. 


3.10.8   High-Order  Bit  on  Output 

Setting  the  high-order   bit  of   an  output   byte  causes   it   to   be 
transmitted  but  not  interpreted  by  the  driver. 


3.10.9  Side  Effects  of  Setting  Characteristics 

Some  of  the  characteristics  that  a  task  may  set,  or  that  you  may  set 
from  a  terminal,  have  side  effects  that  should  be  noted. 

e  TC.HLD  —  Unexpected  behavior  can  result  from  a  terminal  in 
hold-screen  mode  if  its  reception  rate  is  much  greater  than 
its  transmission  rate.  (The  DHll  supports  split  baud  rates.) 
In  hold-screen  mode  the  terminal  sends  a  CTRL/S  during 
reception  of  an  output  stream,  when  the  screen  is  nearly  full. 
Output  is  resumed  —  another  screen-full  —  when  you  type 
SHIFT/SCROLL  (the  terminal  generates  CTRL/Q) .  Thus,  no  output 
is  lost  as  a  result  of  scrolling  off  the  screen  before  you  can 
read  it.  However,  if  the  terminal's  transmission  rate  is  far 
below  its  reception  rate,  some  unread  output  may  scroll  out  of 
sight  before  the  CTRL/S  can  be  transmitted. 

A  related  point  to  note  is  that  some  terminals  and  interfaces 
are  hardware  buffered.  This  fact  can  cause  obscure  timing 
problems  for  tasks  that  try  to  implement  hold-screen  mode. 

e  TC.SMR  —  If  this  characteristic  is  asserted  (that  is,  if 
lower-/uppercase  conversion  is  disabled  by,  for  example,  SET 
/LOWER-TI:),  the  two  characters  175(8)  and  176(8)  are 
interpreted  as  (  (right-brace)  and  (tilde),  respectively. 
If  TC.SMR  is  not  asserted,  these  two  characters  act  as 
Altmodes.  That  is,  they  act  as  line  terminators  that  do  not 
advance  the  cursor  to  a  new  line.   Altmodes  are  npt  echoed. 


3.10.10  Unsolicited-Input-Character  ASTs  for  Tasks  Attaching  Several 
Terminals 

For  a  task  that  attaches  several  terminals  (for  example,  a  reentrant 
language  processor),  the  handling  of  unsolicited  input  requires 
special  care.  When  the  terminal  driver  passes  an  unsolicited  input 
character  to  a  task,  it  does  not  pass  any  information  about  which  of 
several  terminals  generated  the  character.  The  task  must  ascertain 
this  for  itself. 
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One  solution  is  for  tht  task  to  name  uniquely  the  AST  entry  points  for 
each  attached  terminal.  Each  separate  AST  then  identifies  its 
terminal  before  branching  to  a  common  routine  that  processes  the 
unsolicited  character.   For  example: 

ATTl:   OIO$C  lO.ATA, . . . ,<UIC1> 

BR  CONT 
ATT2:   OIO$C  lO.ATA, . . . ,<UIC2> 

BR  CONT 


UICl:   MOV  il,-(SP) 

BR  UIC 
UIC2:   MOV  #2,-(SP) 

BR  UIC 


UIC:    MOV  (SP)+, INDEX 


3.10.11  Direct  Cursor  Control 

The  terminal  driver  generally  examines  the  output  stream  in  order  to 
keep  track  of  the  cursor's  horizontal  position  (so  that  output  can  be 
wrapped  around  or  discarded).  Therefore,  tasks  that  want  to  use 
direct  cursor  control  should  use  lO.WALs.  This  prevents  the  terminal 
driver  from  inserting  CR/LFs  (that  the  task  considers  spurious)  into 
the  output  stream.  FORTRAN  WRITE  statements  become  lO.WVBs,  which  are 
interpreted  by  the  driver.  To  prevent  this,  a  FORTRAN  task  can  use 
the  CALL  QIO  routine  or  can  issue  carriage  returns  at  frequent 
intervals  (to  make  the  driver  think  the  cursor  is  always  well  to  the 
left  of  the  rightmost  column,  and  therefore  no  CR/LFs  need  be  emitted 
to  keep  the  cursor  on  the  screen) . 


3.10.12  DLll  Receiver  Interrupt  Enable 

For  hardware  reasons,  a  DLll  is  susceptible  to  losing  receiver 
interrupt  enable  in  its  Receiver  Status  Register.  The  disabling  of 
the  receiver  interrupt  bit  causes  the  terminal  to  print  output 
requests  but  not  to  respond  to  input  (for  example,  the  terminal  does 
not  echo  input  characters)  .  The  terminal  driver  has  no  mechanism  for 
recognizing  the  disabling.  Therefore,  it  cannot  recover.  The  bit 
must  be  reset  with  an  NCR  OPEN  command,  the  console  switch  register, 
or  a  periodically  rescheduled  task. 


3.10.13  Loadable  Driver  Restrictions 

Checkpointing  during  terminal  input,  variable-length  terminal  buffer 
support,  and  escape  sequence  support  require  the  presence  of 
conditionally  assembled  Executive  support.  If  a  loadable  terminal 
driver  supports  one  of  these  features  and  the  Executive  does  not  (or 
vice  versa) ,  the  best  that  can  happen  is  an  undefined  global  when  the 
terminal  driver  is  built.   At  worst,  the  system  is  corrupted. 
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4 . 1   INTROkMlCTIOM 

The  virtual  terminal  driver  supports  offspring  task  use  of  virtual 
terminals  in  RSX-llM-PLUS  systems.  Virtual  terminals  are  not  physical 
hardware  devices;  they  are  actually  implemented  in  software  through 
the  use  of  data  structures  created  by  the  RSX-llM-PLUS  Executive. 
Virtual  terminals  are  created  by  the  Executive  when  requested  by 
parent  tasks  with  the  Create  Virtual  Terminal  directive.  Virtual 
terminals  are  useful  in  batch  processing  and  other  processing 
environments  in  providing  noninteractive  terminal  I/O  support  for 
offspring  tasks,  eliminating  the  need  for  operator  intervention. 

Offspring  task(s)  "spawned"  by  or  "connected"  to  the  parent  task  that 
created  the  virtual  terminal  can  perform  terminal  I/O  operations  with 
the  virtual  terminal  in  the  same  manner  as  with  physical  terminals. 
Virtual  terminals  differ  from  physical  terminals  in  that  they  receive 
input  from  or  output  to  a  program  (the  parent  task),  rather  than  from 
a  keyboard  or  to  a  display  (or  printer) ,  respectively. 


4.2  GET  LUN  INFORMATION  MACRO 

Word  2  of  the  buffer  filled   by  the  Get   LUN   Information   system 

directive   (the   first  characteristics  word)   contains  the  following 

information  for  virtual  terminals.   A  setting  of  1  indicates  that   the 
described  characteristic  is  true  for  virtual  terminals. 

Bit    Setting  Meaning 

0  1  Record-oriented  device 

1  1  Carriage-control  device 

2  1  Terminal  device 

3  0  Pile-structured  device 

4  0  Single-directory  device 

5  0  Sequential  device 

6  0  Reserved 

7  0  User-mode  diagnostics  supported 
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Bit 
• 
9 

1 
1 
1 
1 
1 
1 


Setting  Meaning 

0  Msssbus  device 

0  Unit  software  write-locked 

0  Input  spooled  device 

0  Output  spooled  device 

0  Psejdo  device 

0  Dijtvice  mountable  as  a  commanications  channel 

0  Device  mountable  as  a  FILES-11  volume 

0  Device  mountable 


Words  3  and  4  are  undefined.  Word  5  specifies  the  maximum  byte  count 
(that  is,  maximum  buffer  size)  to  which  offspring  requests  will  be 
truncated;  this  value  is  specified  by  the  parent  task  in  the  Create 
Virtual  Terminal  system  directive,  as  described  in  the  RSX-llM/M-PLUS 
Executive  Reference  Manual. 


4.3   010  MACRO 

Table  4-1  lists  the  standard  and  device-specific  functions  of  the   010 
macro  that  are  valid  for  virtual  terminals. 

Table  4-1 
Standard  and  Device-Specific  QIC  Functions  for  Virtual  Terminals 


Format 


STANDARD  FUNCTIONS: 
OIOSC  lO.ATT,. 
OIOSC  lO.DBT,. 
OIOSC  lO.KIL,. 
OIOSC  lO.RLB,. 
OIOSC  lO.RVB,. 


OIOSC  IO.WLB,o 
OIOSC  :O.WVB,. 


.  ,<stadd,size> 
.  ,<stadd,size> 


.  ,<stadd  ,size,stat> 
.  ,<stadd  ,sl ze,stat> 


Function 


Attach  device 

Detach  device 

Cancel  I/O  request 

Read  logical  block 

Read  virtual  block 
(effects  lO.RLB) 

Write  logical  block 

Write  virtual  block 
(effects  lO.WLB) 


e 


(continued  on  next  page) 
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Table  4-1   (Cont.) 
Standard  ard  Device-Specific  QIO  Functions  for  Virtual  Terminals 


Format 

Function 

DEVICE-SPECIIIC  FUNCTIONS: 
OIOSC  I0.STC,...,<cb,8w2,swl> 

QIO$C  SF.GMC,. . .,<8tadd,size> 

QIO$C  lO.GTS,. . . ,<stadd,size> 

QIO$C  10. RPR, . . . ,<stadd,slze, [tmo] , 
pradd,prsize,vfc> 

QIO$C  SF.SMC, . . . ,<stadd,slze> 

Set  terminal  characteristics 
(enable/disable  intermediate 
I/O  buffering,  or  return  I/O 
completion     status     to 
offspring  task) 

Get  multiple  characteristics 

Get  terminal  support 

Read  logical  block 
after  prompt 

Set  multiple  characteristics 

size 


The  size  of  the  data  buffer  in  bytes  (must  be  greater  than  0) . 
The  buffer  must  be  located  within  the  addressing  space  of  the 
parent  or  offspring  task  issuing  ths  I/O  request. 


stadd 


The  starting  address  of  the  data  buffer.  The  address  must  be 
word  aligned  for  SF.GMC,  10. GTS,  and  SF.SMC;  otherwise,  it  may 
be  aligned  on  a  byte  boundary. 


Stat 


eb 


The  I/O  completion  status  code,  specified  by  the  parent  task, 
tha^  is  issued  by  the  virtue'  terminal  driver  in  response  to  an 
offijpring  task's  read  request  upon  successful  completion. 


Characteristic  bits  to  become  set,   selecting   the  following 
virtual  terminal  functions: 


cb  Value 
0 


Bits  Set 
none 


0  and  1 


Function 

Enable  intermediate 
buffering  in  the  Executive 
pool 

Return  the  specified 
virtual  terminal  I/O 
completion  status  to  the 
requesting  offspring  task 


Disable 
buffering 


intermediate 


Return     status      for 
offspring  write  request 
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The  I/O  conpletion  code  for  I/O  completion  status. 

NOTE 

The  sw2  and  swl  paraneters  are  valid  in 
the  lO.STC  function  only  when  cb"l  or 
cb-3. 

tno 

An  optional  tine-out  count  (see  below), 
vfc 

A  character  tor  vertical  format  control.   See  Table  3-11. 
pradd 

The  starting  address  of  the  prompt  buffer. 

prslze 

The  size  of  the  prompt  buffer  in  bytes.  The  buffer  must  be 
located  within  the  address  space  of  the  offspring  task  issuing 
the  I/O  request. 

4.3.1   Standard  QIO  Functions 

4.3.1.1  10. ATT  -  This  I/O  function  can  be  issued  by  offspring  task 
tasks  to  attach  the  virtual  terminal.  (It  is  illegal  for  parent  tasks 
to  issue  10. ATT).  Attaching  a  virtual  terminal  prevents  other 
offspring  tasks  from  executing  I/O  operations  with  the  virtual 
terminal.  However,  parent  task  I/O  requests  are  always  serviced  when 
issued . 


4.3.1.2  lO.DET  -  This  I/O  function  can  be  issued  by  offspring  tasks 
to  detach  the  virtual  terminal,  making  it  available  for  use  by  other 
offspring  tasks  connected  to  the  same  parent  task.  (It  is  illegal  for 
parent  tasks  to  issue  lO.DET.) 


4.3.1.3  lO.KIL  -  Parent  and  offspring  tasks  can  issue  lO.KIL  to 
cancel  I/O  requests.  An  offspring  task  issuing  lO.KIL  can  result  (n 
IE. ABO  being  returned  to  the  parent  task. 


4.3.1.4  lO.RLB,  lO.RVB,  lO.WLB,  lO.WVB  -  These  read  and  write 
functions  execute  requested  I/O  operations  with  virtual  terminals  in 
the  same  manner  as  with  terminals  described  in  Chapter  2,  except  as 
follows: 

1.  The  virtual  terminal  driver  returns  che  tmo  parameter  of  an 
offsi^.ing  task's  lO.RLB  or  lO.RVB  request,  or  the  vfc 
parameter  of  an  offspring  task's  IO.<<I,B  or  lO.WVB  request  as 
a  stArk  parameter  on  entry  to  the  appropriate  AST  for  the 
pare  c  task. 
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The  virtual  terminal  driver  returns  I/O  completion  status  to 
the  offspring  task  in  response  to  successful  completion  of 
the  offspring  task's  lO.RLB  or  lO.RVB  request;  however,  the 
actual  I/O  completion  status  values  returned  are  specified 
for  data  transfers  in  the  third  parameter  word  of  the  parent 
task's  lO.WLB  or  lO.WVB  response,  or  in  the  second  and  third 
parameters  of  the  parent  task's  lO.STC  function  response  when 
no  data  transfer  is  desired. 


4.3.2   Device-Specific  QIO  Function  (lO.STC) 

The  lO.STC  function  can  be  issued  by  parent  tasks  to  enable/disable 
offspring  task  I/O  buffering  in  secondary  pool,  or  to  force  an 
appropriate  I/O  completion  status  for  an  offspring  task  read  I/O 
request  when  no  data  transfer  is  desired.  Both  of  thvise  applications 
for  the  lO.STC  function  are  described  as  follows. 

Parent  tasks  can  use  lO.STC  to  enable  (or  disable)  intermediate 
buffering  in  secondary  pool.  Intermediate  buffering,  when  enabled,  is 
performed  -^n  offspring  task  virtual  terminal  read  and  write  requests 
when  the  offspring  task  is  checKpointable. 

Thus,  offspring  tasks  can  be  stopped  for  virtual  terminal  I/O  nd 
checkpointed  In  a  manner  similar  to  that  when  physical  terminals  ire 
used.  Whenever  the  virtual  terminal  driver  determines  ^at 
intermediate  buffering  should  not  be  used,  offspring  tasks  that  i  >ue 
terminal  requests  become  locked  in  memory  until  I/O  complet  on; 
transfers  occur  directly  between  parent  task  and  offspring  cask 
buffers  without  intermediate  buffering  in  secondary  pool. 

In  addition  to  the  conditions  that  permit  intermediate  buffering  (when 
.specified),  one  condition  can  automatically  disable  intermediate 
buffering  of  the  parent  task.  If  the  buffer  size  specified  in  the 
Create  Virtual  Terminal  directive  exceeds  the  maximum  size  specified 
at  system  generation  time  (512(10)  maximum),  intermediate  buffering  is 
disabled. 

The  second  application  for  lO.STC  is  to  allow  the  virtual  terminal 
driver  to  return  an  appropriate  I/O  completion  status  in  response  to 
an  offspring  task  read  request.  I/O  status  returned  in  this  manner 
allows  successful  completion  of  the  offspring  task's  request  when  the 
parent  task  determines  that  no  data  transfer  is  desired;  this 
condition  can  occur,  for  example,  when  no  data  is  avail&ble  for  input 
to  the  offspring  task  by  the  virtual  terminal  driver.  When  used  in 
this  manner,  the  lO.STC  function  must  include  three  parameters, 
<cb,sw2,swl>,  as  follows: 


cb 


A  value  of  1  is  specified  to  indicate   that   the   I/O  completion 
status  return  to  the  offspring  task  is  desired. 


NOTE 

If  the  virtual  terminal  is  operating  in  full  duplex  mode, 
a  cb  value  of  1  returns  status  for  an  offspring  read 
request,  and  a  cb  value  of  .1  returns  status  for  an 
offspring  write  request. 
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This  parameter  is  the  second  word  returned  in  the  I/O  completion 
status  indicating  the  number  of  bytes  read  upon  successful 
completion  of  an  offspring  task's  read  request.  However,  since 
no  data  transfer  actually  occurs,  the  value  specified  is  0;  the 
byte  count  of  0  specified  in  this  function  is  legal  (and 
desired),  whereas  a  byte  count  of  0  in  write  operations  is 
illegal  (and  will  result  in  an  error  being  returned  to  the  parent 
task)  . 


sw2 


This  parameter  specifies  the  status  code  to  be  returned  to  the 
offspring  task  by  the  virtual  terminal  driver  in  the  first  word 
of  the  I/O  completion  status.  This  value  is  returned  in  the  high 
byte  and  a  value  of  -«-l  is  returned  in  the  low  byte  of  the  status 
word.  Typical  values  and  the  status  that  each  represent  are 
listed  as  follows: 

Completion  Status  Indicated 

Successful  completion 

Read  terminated  by  carriage 
return 

Read  terminated  by  an  Altmode 

Read  terminated  by  an  escape 
sequence 


Code 

Value 

IS. sue 

+   1 

IS.CR 

U 

IS. ESC 

33 

IS. ESQ 

233 

4.3.3   SF.GMC 


The  Get  Multiple  Characteristics  function  returns  information  on 
terminal  characteristics.  This  function  can  be  issued  by  both  the 
parent  and  the  offspring  tasks.  The  virtual  terminal  driver  returns 
the  characteristics  that  were  set  by  the  previous  corresponding  SF.SMC 
request.  However,  only  the  full  duplex  node  (TC.FDX)  characteristic 
affects  the  operation  of  the  virtual  terminal  'jriver.  The  SF.GMC 
function  is  provided  only  to  maintain  transparency  to  the  offspring 
task. 

Valid  virtual  terminal  characteristics  are  listed  in  Table  4-2. 


4.3.4   ID. GTS 

The  Get  Terminal  Support  function  returns  a  4-word  buffer  of 
information  specifying  which  features  are  a  part  of  the  virtual 
terminal  driver.  The  virtual  terminal  driver  provides  the  10. GTS 
function  only  to  maintain  transparency  to  the  offspring  task.  Table 
2-7  lists  the  options  returned  by  the  full  duplex  terminal  driver.  Of 
those  listed,  the  virtual  terminal  driver  returns  the  following: 

Word  1  —  Fl.BUF,  Fl.RPR,  Fl.UTB,  and  Fl.VBF 

Word  2  ~  F2.SCH  and  F2.GCH 
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4.3.5   10. RPR 

The  Read  After  Prompt  (10. RPR)  function  can  be  issued  only  by  the 
offspring  task.  When  the  offspring  task  issues  this  function,  the 
function  appears  to  the  parent  task  as  a  separate  write  request 
followed  by  a  read  request.   This  function  is  described  In  Chapter  3. 


4.3.6   SF.SMC 

The  SF.SMC  function  allows  a  task  to  set  and  reset  the  characteristics 
of  a  terminal.  Both  the  parent  and  the  offspring  tasks  may  issue  this 
function.  The  parent  task  may  set  virtual  terminals  to  full  duplex 
operation  by  using  the  SF.SMC  function  with  the  characteristics  bit 
TC.FDX.  When  in  full  duplex  mode,  the  virtual  terminal  driver 
attempts  to  process  the  offspring  task's  read  and  write  requests 
simultaneously.  In  order  to  insure  that  these  operations  are 
overlapped,  the  parent  task  should  minimize  the  amount  of  time  it 
spends  in  AST  state. 

The  virtual  terminal  driver  defaults  to  half  duplex  mode. 


Table  4-2  lists  the  characteristics  that 
offspring  task  may  set. 


either   the  parent  or  the 


Table  4-2 
Virtual  Terminal  Characteristics 


Bit  Name 

Octal 
Value 

Meaning  (If  Asserted) 

Default 

Value 

TC . FDX 

64 

Full  duplex  mode 

0 

TC.SCP 

12 

Terminal  is  a  scope 

0 

TC.SMR 

25 

Uppercase  conversion 
disabled 

0 

TC.TTP 

10 

Terminal  type 

0 

4.4   STATUS  RETURNS 

The  error  and  status  conditions  listed  in  Tables  4-3  and  4-4  are 
returned  by  the  virtual  terminal  driver  described  in  this  chapter. 
The  SE.NIH  error  is  returned  by  the  SF.GMC  and  SF.SMC  functions.  For 
this  error,  the  low  byte  of  the  first  word  in  the  I/O  status  block 
contains  IE. ABO.  The  second  word  in  the  I/O  status  block  contains  an 
offset  (starting  at  0)  pointing  to  the  erroneous  byte  in  the  stadd 
buffer. 
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Tabl*  4-3 
Virtual  Terminal  Status  Returns  for  Offspring  Task  Requests 


Code 


IS. sue 


IE. IPC 


IE. ABO 


lE.SPC 


lE.UPN 


SE.NIH 


Reason 


Successful  completion  of  an  offspring  task  read 
request  results  in  an  I/O  completion  status  specified 
in  a  parent  task  QIO  parameter  being  returned. 
Typically,  the  status  information  returned  simulates 
a  subset  of  I/O  returns  normally  produced  by  the 
terminal  drivers  described  in  Chapter  2. 

Successful  completion 

The  operation  specified  in  the  QIO  directive  was 
completed  successfully.  The  second  word  of  the  I/O 
status  block  indicates  the  number  of  bytes 
transferred  on  a  write  operation. 

Invalid  function  code 

The  offspring  task  attempted  a  read  or  a  write 
function  and  the  parent  task  did  not  specify  an  AST 
address  in  its  response  to  the  requested  I/O 
function,  or  the  offspring  task  issued  an  lO.STC  or 
other  invalid  function. 


Request  terminated 

The  offspring  task  issued  lO.KIL  or  the 
eliminated  the  virtual  terminal  unit. 


parent   task 


Illegal  address  space 

Part  or  all  of  the  buffer  specified  for  a  read  or 
write  request  was  outside  of  the  task's  address 
space,  or  a  byte  count  of  0  was  specified. 

Insufficient  dynamic  storage 

The  driver  co'jld  not  allocate  an  AST  block  to  notify 
the  parent  cask  of  an  offspring  task  request,  or  the 
driver  cou'd  not  allocate  an  Intermediate  buffer  in 
the  Executive  pool. 

A  terminal  characteristic  other  than  those  in  Table 
4-2  was  specified,  or  an  offspring  task  attempted  to 
assert  TC.FDX. 
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Table  4-4 
Virtual  Terminal  Status  Returns  for  Parent  Task  Requests 


Code 


IS. sue 


IE. EOF 


IE. BAD 


IE. DUN 


IB. IPC 


SE.NIH 


Reason 


Successful  completion 

The  operation  specified  in  the  QIO  directive  was 
completed  successfully.  The  second  word  of  the  I/O 
status  block  indicates  the  number  of  bytes 
transferred  on  a  read  or  write  operation. 

End  of  file  encountered 

The  lO.STC  function  was  completed  successfully. 

Dad  parameters 

The  parent  task  specified  a  buffer  size  that  exceeded 
the  system  maximum  specified  at  system  generation 
time. 

Device  not  attachable 

An  10. ATT  or  lO.DET  function  was  issued  by  the  parent 
task. 

Invalid  function  code 

A  read,  write,  or  lO.STC  function  was  issued  without 
a  pending  offspring  task  request.  This  status  can 
occur  if  the  offspring  task  cancels  a  pending  read  or 
write  request.  This  function  code  is  also  returned 
when   lO.STC   is   issued    to    enable    intermediate 

terminal  unit  whose  buffer 

Create   Virtual    Terminal 

system  maximum  specified  at 


buffering   on   a   virtual 
size,   specified   in   the 
directive,   exceeds   the 
system  generation  time. 


A  terminal  characteristic  other  than  those   in   Table 
4-2  was  specified  in  an  SF.GMC  or  SF.SMC  request. 
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DISK  DRIVERS 


5.1   ISTRODOCTION 


The  RSX-llM  disk  drivers  support  the  disks  summarized   in  Table 
Subsequent  sections  describe  these  devices  in  greater  detail. 


5-1. 


All  of  the  disks  described  in  this  chapter  are  accessed  in  essentially 
the  same  manner.  Up  to  eight  disks  of  each  type  (except  RXOl,  KX02, 
RX50,  RD51,  RC25,  RLOl,  RL02,  RA60,  RABO ,  or  RA81)  may  be  connected  to 
their  respective  controllers.  Disks  and  other  file-structured  media 
are  divided  logically  into  series  of  256-word  blocks. 


5.1.1  RF11/R811  Fixed-Head  Disk 

The  RFll  controller/RSll  fixed-head  disk  provides  random  access  bulk 
storage.  It  features  fast  track-switching  time  and  a  redundant  set  of 
timing  tracks. 


5.1.2  RS03  Fixed-Head  Disk 


The  RS03  (RH11-RH70  controller/RS03  fixed-head  disk)  is  a  fixed-head 
disk  that  offers  speed  and  efficiency.  With  64  tracks  per  platter  and 
recording  on  one  surface,  the  RS03  has  a  capacity  of  262,144  words. 


5.1.3  RS04  Fixed-Head  Disk 

The  RS04  (RH11-RH70  controller/RS04  fixed-head  disk)  is  similar  to  the 
RS03  disk  and  interfaces  to  the  same  controller,  but  provides  twice 
the  number  of  words  per  track  by  recording  on  both  surfaces  of  the 
platter,  and  thus  has  twice  the  capacity. 


5.1.4   RP11/RP02  or  RP03  Pack  Disks 

The  RPll  co.itroller/RP02   or   RP03   pack   disk   consists   of   20  data 

surfaces   and   a   moving   read/write  h^ad.   The  RP03  has  twice  as  many 

cylinders,  and  thus  double  the  capacity  of  the   RP02.    Only   an  even 
number  of  words  can  be  transferred  in  a  read/write  operation. 
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Table  S-1 
Standard  Disk  Devices 


Controller/ 
Drive 

RPM 

Sees 

Trks 

Cyls 

Bytes/ 
Drive 

Decimal 
Blocks 

Rril/RSll 

1800 

— 

128 

524,288 

1024 

RHXX/RS03 

3600 

64 1 

64 

524,288 

1024 

RHXX/R^04 

3600 

64 1 

04 

1,048,576 

2048 

RPllE/i:iPR02 

2400 

10 

20 

200 

20,480,000 

40,000 

RP11C/RP03 

2400 

10 

20 

400 

40,960,000 

80,000 

RHXX/RN02 

2400 

32 

823 

67,420,160 

131,680 

RHXX/RH03 

3600 

32 

823 

67,420,160 

131,680 

RH70/RH05 

3600 

32 

823 

256,196,608 

500,384 

RH11/RP04,RP05 

3600 

22 

411 

87,960,576 

171,798 

RH70/RP06 

3600 

22 

815 

174,423,040 

340,670 

RH70/RP07 

3600 

50 

6302 

516,096,000 

1,008,000 

RH70/RM80 

3603 

31 

5592 

124,214,272 

242,606 

RK11/RK05 

1500 

12 

200 

2,457,600 

4800 

RLll/RLOl 

2400 

403 

256 

5,242,880 

10,240 

RL11/RL02 

2400 

40* 

bl2 

10,485,760 

20,480 

RK611/RK06 

2400 

22 

411 

13,888,512 

27,126 

RK611/RK07 

2400 

22 

815 

27,810,800 

53,790 

RXll/RXOl 

360 

264 

77 

256,256 

494 

RX211/RX02 

360 

264 

77 

512,512 

988 

UDAS0/RA80 

3600 

31 

14 

546 

121,325,568 

236,964 

UDAS0/RA81 

3600 

51 

14 

1248 

456,228,864 

891,072 

UDA50/RA60 

3600 

42 

2382 

204,890,112 

400,176 

RC25 

2850 

31 

796 

26,061,824 

50,902 

RD51 

3600 

16 

306 

10,027,008 

19,584 

RX50 

300 

10 

80 

409,600 

800 

1.  The   RS03   has   64   words   per   sector; 
words/sector . 


the   RS04   has 


128 


2.  The  RP07  and  the  FtM80  each  have  two  additional  CE  cylinders. 

3.  The  RLOl  and  RL02  each  have  128  wore   f-er  sector. 

4.  The  RXOl  has  64  words  per  sector;  the  RX02  has  128  words  per 
sector . 
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5.1.5   IIM02/RM03/IW05/RM80  Pack  Disk 

Th«  RH02/RM03,  RM05,  and  RM80  ar*  MASSBliS  disk  drivaa  and  adcpters 
that  use  tha  axisting  MASSBUS  controller.  With  a  single  head  per 
surface,  they  provide  a  1.2  megabyte- per- second  data  transfer  rate. 
The  RM03,  RM05,  and  RM80  are  used  with  the  RH70  controller  on 
PDP-11/70  systems.  All  other  systems  use  the  FtM02  with  the  RHll 
controller. 


5.1.6  RP04,  >POS,  BPOe  Pack  Dicks      ^ 

The  RP04  or  RP05  (RH11-RH70  controller/RP04  or  RPOS  ptK.''.     diJk)  pack 

disks   consist  of  19  data  surfaces  and  a  moving  read/write  head.  Both 

offer  large  storage  capacity  with  rapid  access  time.    The   RP06  pack 

disk   hai.  approximately   twice  the  capacity  of  the  RP04  or  RPOS.  The 

RP07  fixed-media  disk  has  approximately  3  times  the   capacity   of  the 
RPOS. 


5.1.7   RK11/RK05  or  RK03F  Cartridge  Disks 

The  RKll *controller/RKOS  DKCpack  cartridge  disk  is  an  economical 
storage  system  for  medium- volume,  random  access  storage.  The 
removable  disk  cartridge  offers  the  flexibility  of  large  off-line 
capacity  with  rapid  transfers  of  files  between  on-  and  off-line  'jnits 
without  necessitating  copying  operations.  The  RK05F  has  twicf  the 
storage  capacity  of  the  RKOS  and  has  a  fixed  (nonremovable,  disk 
cartr  idc;e. 


5.1.8  RLll/RLOl  or  RL02  Cartridge  Disk 

The  RLOl  is  a  low-cost,  single-head  per  surface  disk  with  a  burst  data 
transfer  rate  of  512  kilobytes  per  sacond.  The  storage  capacity  of 
the  RL02  is  twice  that  of  the  RLOl. 


5.1.9   RK611/RR06  or  RK07  Cartridge  Disk 

The  RK611  controller/RK06  cartridge  disk  is  a  removable,  random 
accsss,  bulk-storage  system  with  three  data  surfaces.  The  storage 
capacity  is  6,944,256  words  per  pack.  The  system,  expandable  to  eight 
drives,  is  suitable  for  medium  to  large  systems. 

The  RK611  controller/RK07  cartridge  disk  is  generally  similar  to  the 
RK611/RX06,  except  storage  capacity  is  increased  to  approxiRtately 
13,905,400  words  per  pack.  Both  RK06  and  RK07  disks  can  use  the  same 
RK611  controller;  mixing  RK06  and  RK07  disks  on  the  same  conttoller 
is  permitted. 


5-3  April  1983 


DISK  DIIVIM 

5.1.10   RXll/RXOl  Fl«iibl«  Disk 

Th«  RXll  controll«r/RX01  flexible  disk  is  an  •conomical  storage  system 
for  low-volume,  random  access  storage.  Data  is  stored  in  twenty-six 
64-word  sectors  per  track;  there  are  77  tracks  per  disk.  Data  may  be 
accessed  by  physical  sector  or  logical  block.  If  logical  or  virtual 
block  I/O  is  selected,  the  driver  reads  four  physical  sectors.  These 
sectors  are  interleaved  to  optimise  data  transfer.  The  next  logical 
sector  that  falls  on  a  new  track  is  skewed  by  six  sectors  to  allow  for 
track-to-track  switch  time.  Physical  block  I/O  provides  no 
interleaving  or  skewing  and  provides  access  to  all  2002  sectors  on  the 
disk.  Logical  or  virtual  I/O  starts  on  track  1  and  provides  access  to 
494  logical  blocks. 


5.1.11   RX211/RX02  Flexible  Disk 

The  RX211  control ler/RX02  flexible  disk  is  an  economical  storage 
system  for  low-volune,  random  access  storage.  It  is  capable  of 
operating  in  either  an  industry-standard,  single-density  mode  (as 
stated  for  the  RXll/RXOl  flexible  disk),  or  a  double-density  mode  (not 
industry  standard).  In  the  single-density  mode,  each  drive  can  store 
data  exactly  as  stated  in  Section  5.1.10.  In  the  doublA-density  mode, 
data  is  stored  in  twenty-six  128-word  sectors  per  track;  there  are  77 
tracks  per  disk.  The  RX211/RX02  operating  in  the  single-density  mode 
can  read  disks  written  by  an  RXll/RXOl  flexible  disk  system.  In 
addition,  disks  written  by  the  RX211/RX02  operating  in  the 
single-density  mode  can  be  read  by  the  RXll/RXOl  flexible  disk  system. 


5.1.12   NL-11  Disk  ■■olatoc 

The  ML-11  is  a  fast,  random  access,  block-mode  MOS  memory  system.  The 
RSX-llM  and  RSX-llM-PLUS  operating  systems  treat  the  NL-11  as  a  disk. 
However,  since  it  is  not  a  disk,  the  statistics  in  Table  5-1  do  not 
apply.  Unlike  a  disk,  the  number  of  bytes  per  drive  varies.  One 
ML-11  provides  from  512  blocks  to  8192  blocks  of  storage. 


5.1.13   ODA50/RA60/RA80/RA81  Disks 

The  UDA  controller  is  an  intelligent  disk  controller,  which  ccntains  a 
high-speed  microprogrammed  processor  capable  of  performing  all  disk 
functions,  including  data  handling,  error  detection  and  correction, 
and  optimisation  of  disk  drive  activity  an<!  data  transfers.  The  types 
of  drives  that  can  be  connected  to  the  UDA50  controllers  are  the  RA60 
disk  drive,  which  has  a  removable  pack,  and  the  RA80  and  RA81,  both  of 
which  are  fixed  media  drives.  (For  data  capacities  and  rates,  see 
Table  5-1.)  Up  to  four  of  these  drives  can  be  connected  to  a  UDA,  in 
any  desired  combination. 

The  UDA  controller  also  has  two  addressable  registers  in  the  I/O  page 
that  are  used  for  the  initialization  sequence  and  to  initiate  polling 
of  command  packet  buffers  in  memory.  In  addition,  this  controller  is 
also  capable  of  carrying  out  an  extensive  self-test  on  power-up  or 
initialisation. 
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5.1.14   RC25  Disk  SubsyatMi 

Th«  RC25  Subsystem  combinas,  in  on*  package,  a  controller  and  a  single 
disk  drive  that  has  a  removable  disk  and  a  fixed  disk.  These  disks 
reside  in  the  drive  as  two  separate  logical  units  on  a  single  spindle. 
Their  site  is  the  same.  Both  are  single  eight-inch  disks  with  two 
surfaces,  ^rd  both  disks  have  the  same  liata  capacity.  But 
mechanically  they  are  different:  One  is  a  removable  front-loading 
cartridge  disk,  while  the  other  cannot  be  removed  from  the  drive.  The 
drive  is  designed  with  loadable  Winchester  type  heads. 

An  additional  disk  drive  can  be  added   to  the   RC25   Disk   Subsystem, 

providing   a   dual   spindle   configuration  with   two   fixed   and   two 

removable  disks.  The  added-on  disk  drive  is  a  slave  to  the  disk 
subsystem  that  has  the  controller. 


5.1.15  RD51  Fixed  5.25  Dlsk/RXSO  Flexible  5.25  Disk 

This  subsystem  is  designed  to  serve  a  hard (RD) /f lexible(RX)  disk 
combination  that  can  be  used  as  a  mass  storage  medium  for  small 
systems.  The  basic  configuration  for  thii  mass  storage  scheme  is  an 
RDSl  fixed  disk  drive  and  an  RX50  flexible  dual  disk  drive.  In  this 
configuration,  the  RD51  is  the  system  device  and  the  RX50  is  used  as  a 
data  device  and/or  as  a  backup.  The  RX50  dual  disk  is  addressed  as 
two  separate  units  resulting  in  a  basic  configuration  of  three  disk 
units.  Also,  another  R051  can  be  added  to  increase  storage  capacity. 
Some  of  the  characteristics  of  the  RD/RX  drives  are  given  in  Table  5-1 
and  in  the  following  paragraphs. 

The  RD51  disk  drive  is  a  5.25  inch  fixed  disk  with  Winchester  type 
heads.  It  has  two  disks  with  four  data  surfaces.  The  RDSl  is  soft 
sectored  and  field  formattable.  The  headers  for  each  sector  contain 
the  sector's  cylinder  number,  head  number,  and  sector  number.  The 
sector  number  is  the  logical  sector  number  (0-15)  that  reflects  the 
sector  interleave  of  the  disk. 

The  RX50  dual  diskette  drive  is  a  compact  mass  storage  drive  with  two 
access  slots.  Each  slot  can  hold  a  single-sided  5.25  flexible  disk. 
These  diskettes  are  firm  sectored  and  are  not  field  formattable. 
Every  track  has  sectors  numbered  from  1  to  10.  The  two  diskettes 
share  the  same  head  transport  mechanism. 


5.2   GET  LON  IHPORHATION  HACBO 

Word  2  of  the  buffer  filled  by  the  Get  LUN  Information  system 
directive  (the  first  characteristics  word)  contains  the  following 
information  for  disks.  A  bit  setting  of  1  indicates  that  the 
described  characteristic  is  true  for  disks. 
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Bit 

0 


Setting 
0 
0 
0 

1 

0 
0 

1 

X 

X 

0 
0 
0 
0 
0 

1 
1 


Meaning 

Record-or i«nt«d  device 

Carriage-control  device 

Terminal  device 

Pile  structured  device 

Single-directory  device 

Sequential  device 

Mass  storage  device 

User-mode  diagnostics  supported  (device 
dependent) 

Device  supports  22-bit  direct  addressing 

Unit  software  write-locked 

Input  spooled  device 

Output  spooled  device 

Pseudo-device 

Device  mountable  as  a  communications 
channel 

Device  mountable  as  a  PILES-11  volume 

Device  mountable 


Words  3  and  4  of  the  buffer  contain  the  maximum  logical  block  number. 
Note  that  the  high  byte  of  U.CW2  is  undefined.  The  user  should  clear 
the  high  byte  in  the  buffer  before  using  the  block  number.  For  the 
RA80  disk,  these  two  words  are  undefined  until  the  device  has  been 
accessed  at  least  once.  Word  5  indicates  the  default  buffer  size, 
which  Is  512  bytes  for  all  disks. 


5.3   QIO  MACRO 

This  section  summarizes   the 
functions  for  disk  drivers. 


standard,   and   device-specific   QIO 


5.3.1   Standard  QIO  Functions 

Table  5-2  lists  the  standard  functions  of  the  QIO  macro  that  are  valid 
for  disks. 
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Tabic  S-2 
Standard  QIO  Functions  for  Disks 


Format 

Function 

oiosc 

10. ATT,. 

Attach  davic*^ 

QIOSC 

lO.DET, . 

Datach  davica 

0IO$C 

lO.KIL,. 

Kill  I/o2 

OIOSC 

lO.RLB,. 

. .,<8tadd,siz«, ,blkh,blkl> 

READ  logical  block 

OIOSC 

lO.RVB,. 

. . ,<stadd,size, ,blkh,blkl> 

READ  virtual  block 

OIOSC 

lO.WLB,. 

. . ,<8tadd,8is*, ,blkh,blkl> 

WRITE  logical  block 

QIOSC 

lO.WLC,. 

.  .,<stadd,sizcblkh,blkl> 

WRITE  logical  block 
foliowad  by  write 
chack^ 

OIOSC 

lO.WVB,. 

. . ,<stadd,sii«, ,blkh,blkl> 

WRITE  virtual  block 

1.  In  RSX-llM  systams,  only  unmountad  volumes  may  be  attached; 
in  RSX-llM-PLUS  systems,  only  volumes  mounted  foreign  may  be 
attached.  Any  other  attempt  to  attach  a  mounted  volume  will 
result  in  an  lE.PRI  status  being  returned  in  the  I/O  status 
doubleword. 

2.  In-progress  disk  operations  are  allowed  to  complete  when 
lO.KIL  is  received,  because  they  take  such  a  short  time.  I/O 
requests  that  are  queued  when  lO.KIL  is  received  are  killed 
immediately.  An  IE. ABO  status  is  returned  in  the  I/O  status 
doubleword. 


3.  Not  supported  on  RXOl  or  RX02  flexible  disks. 


•tadd 


The  starting  address  of  the  data   buffer   (must   be  on 
boundary) . 


word 


•  ft* 


The  data  buffer  size  in  bytes  (must  be  even,  greater  than  0,  and, 
for  the  RP02  and  RP03,  aliso  a  multiple  of  four  bytesi  . 


blkh/blkl 


Block  high  and  block  low,  combining  to  form  a  double-precision 
number  that  indicates  the  actual  logical/virtual  block  address  on 
the  disk  where  the  transfer  starts;  blkh  represents  the  high  8 
bits  of  the  address,  and  blkl  the  low  Ifi  bits. 
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lO.RVB  and  lO.WVB  ar«  asBociatad  with  fila  operations  (saa  the 
IAS/RSX-11  I/O  Oparations  Reference  Manual) .  For  these  functions  to 
be  executed,  a  fill  mrst  be  open  on  the  specified  LUN  If  the  volume 
associated  with  tho  LUN  Is  mounted.  Otherwise,  the  virtual  I/O 
request  Is  converted  tu  a  logical  I/O  request  using  the  specified 
block  numbers. 


NOTE 


When  wrl 
task  mu 
Control 
necepsar 
the  file 
created 
the  file 
put   an 
the  end- 
before 
. EXTND 
TAS/RSX- 
Manual . ) 


ting  a  new 
St  expllcl 
System  llbr 
y  tc  rese 
or  the  fl 
with  enough 
In  addlt 
appropriate 
of-flle  bl 
closing  the 
routine   d 

11       1/2. 


file  using  QIOs,  the 
tly  Issue  .EXTND  Pile 
ary  routine  calls  as 
rve  enough  blocks  for 
le  mitst  be   Initially 

blocks  allocated  for 
Ion,   the   task   must 

value  In  tho  FDB  for 
ock   number   (F.EFBK) 

file.  (Refer  to  the 
escrlptlon  In  the 
Operations   Reference 


Each  disk  driver  supports  the  subfunctlon  bit  IQ.X:  Inhibit  retry 
attempts  for  error  recovery.  The  subfunctlon  bit  is  used  by  ORing  it 
into  the  desired  QIO;   for  example: 


QIO$C  lO.WLBlIQ.X,.. .,<stadd,slze,,blkh,blkl> 

The  IQ.X  subfunctlon   permits   user-specified   retry 
applications  in  which  data  reliability  must  be  high. 


algorithms   for 


Thf  overlapped  seek  drivers  for  RSX-llM-PLUS  support  subfunctlon  bit 
IQ.Q:  queue  the  request  Immediately  without  doing  a  seek  (that  is, 
use  implied  seeks). 


S.i.2     Device-Specific  QIO  Functions 

The  device-specific  functions  of  the  QIO  macro  are  valid  for  the   RXOl 
only;   they  are  shown  in  Table  5-3. 


Table  5-3 

Device-Specific  Functions  for  the 

RX01,RX02,  RLOl,  and  RL02   Disk  Drivers 


# 


Format 

Function 

QIO$C 

lO.RPB, . . . ,<stadd,size, 

,,pbn> 

Read  physical  block 

QIO$C 

10. SEC, . . . 

Sense  diskette  characteristics 
(RX02  only) 

QIO$C 

lO.SMD, . . . ,<density, ,> 

SET  media  density  (RX02  only) 

QIO$C 

lO.WDD, ...,<stadd,size; 

»»pbn> 

Write  physical  block  (with  deleted 
data  mark)  (RXOl  and  RX02  only) 

0IO$C 

lO.WPB,.. .,<stadd,size, 

,,pbn> 

Write  physical  block 
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•tadd 


Th*  starting  addraas  of  tha  da(:a  buffar   (nuat  ba  on  a  word 
boundary)  . 


■  is* 


pbn 


Tha  data  buffer  size  in  bytas  must  ba  avan  and  greater  than  C). 


The  physical   block  number  where   the   transfer   stirts    (no 
validation  will  occur). 


density 

The  media  density  as  follows: 

0  ■  single  (RXOl-compatible)  density 
2  -  double  density 


5.3.3  Davica-Spacif ic  QIO  Function  for  tha  RA80 

The  RA80  driver  supports  the  device-specific   QIO  function  shotm   in 
Table  5-4. 


Table  5-4 
Device-Specific  QIO  Function  for  the  RA80  Disk  Driver 


Format 

Function 

QIOSC  lO.RLC,.. .,<stadd,size,,blkh,blkl> 

Read  Logical  with  Read  Check 
modifier 

5.4   STATUS  RETURNS 

The  error  and  status  conditions  listed  in  Table  5-5  are   returned   by 
the  disk  drivers  described  in  this  chapter. 


Table  5-5 
Disk  Status  Returns 


Code 

Reason 

IS. sue 

Successful  completion 

1 

The  operation  specified  in  the   QIO 
completed  successfully.   The  second 
status  block  can   be  examined   to 
number   of   bvtes   processed,   if 
involved  rea^^ing  or  writing. 

directive  was 

word  of  the  I/O 

determine   the 

the  operation 

(continued  on  next  parje) 
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Table  5-5   (Cont.) 
Disk  Status  Returns 


Code 

Rbason 

IS.PND 

I/O  request  pending 

The  operation  specified  in  the   QIO  directive  has 
not   yet   been  executed.    The  I/O  status  block  is 
filled  with  OS. 

IS.RDD 

Deleted  data  mark  read 

•  ■■  ■  '      ■     :.■ 

A  deleted  record  was  encountered  while  executing  an 
lO.RPB  function.   The  second  word  of  the  I/O  status 
block  can  be  examined  to  determine   the   number   of 
bytes  processed  (RXOl  and  RX02  only) . 

XL. ABO 

Request  <iborted 

An  I/O  request  was  queued  (not  yet   acted   upon   by 
the  driver)  when  an  lO.KIL  was  issued. 

lE.ALN 

File  ai ready  open 

The  task  attempted  to  open  a  file  on   the   physical 
device   unit  associated   with  specified  LUN,  but  a 
file  has  already  been  opened  by  the  issuing  task  on 
that  LUN. 

lE.BLK 

Illegal  block  number 

An  illegal   logical   block   number  was   specified. 
This  code  would  be  returned,  for  example,  if  block 
4800  were  specified  for   an   RK05  disk,   on  which 
legal   block  numbers  extend   from  0  through  4799. 
lE.BLK  would  also  be  returned   If  an  attempt   was 
made   to  write  on  the  last  track  of  an  RK06  disk. 
(See  Section  5.5.) 

lE.BBE 

Bad  block  error 

.. 

The  disk  sector  (block)  being  read  was  marked  as  a 
bad  block  In  the  header  word. 

IE, BYT 

Byte-aligned  buffer  specified 

,  . 

Byte  alignment  was  specified  for  a  buffer,  but  only 
word   alignment   is  legal  for  disk.   Alternatively, 
the  length  ol  a  buffer  Is  not  an  appropriate  number 
of   bytes.    For   example,   all   RP03  and  RPOl:  d'sk 
transfers  must  be  multiples  of  four  bytes. 

lE.DNR 

Device  not  ready 

The  physicaJ.   device   unit   specified   in   the   QIO 
directive  was  iiot  ready  to  perform  the  desired  I/O 

operation. 

(continued  on  next  page) 
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Tabic  5-5   (Cont.) 
Disk  Status  Returns 


Coda 

Raason 

IB.PHR 

Patal  hardwara  ai'ror 

Tha  controller  Is  physically  unable   to   reach   the 
location  where   Input/output  operation   is   to  be 
performed.   The  operation  cannot  be  completed. 

IE. IPC 

Illegal  function 

A  function  code  was  specified   in  an   I/O  request 
that  is  illegal  for  disks. 

IB.NLN 

Pile  not  open 

Ihe  task  attempted  to  close  a  file  on  the  physical 
device   unit  associated  with  the  specified  LUN,  but 
no  file  was  currently  open  on  that  LUN. 

IE. NOD 

Insufficient  buffer  space 

Dynamic  storage  space  has  been  depleted,  and   there 
was  insufficient  buffer  space  available  to  allocate 
a  secondary  control  block.   Por  example,  if  a   task 
attempts   to  open  a   file,   buffer   space  for  the 
window  end  file  control  block  must  be  supplied   by 
the  Executive.   This  code  is  returned  when  there  is 
not  enough  space  for  this  operation. 

lE.OPL 

Device  off  line 

The  physical  device  unit  associated   with   the   LUN 
specified   in   the   QIO  directive  was  not  en  line. 
When   the   system  was  booted,   a   device   check 
indicated  that  this  physical  device  unit  was  not  in 
the  configuration. 

Illegal  read  overlay  request 

lE.OVR 

A  read  overlay  was   requested,   and   the   physical 
device   unit  specified  in  the  QIO  directive  was  not 
the  physical  device  unit  from  which   the   task   was 
installed.   The   read  overlay  function  can  only  be 
executed  on  the  physical  device  unit  from  which  the 
task  image  containing  the  overlays  was  installed. 

lE.PRI 

Privilege  violation 

The  task  that  issued  the  request  was  not  privileged 
to   execute   that   request.   For  disk,  this  code  is 
returned  if  a  nonprivileged  task  attempts  to   read 
or  write  a  mounted  volume  directly  (that  is,  using 
lO.RLB  or  lO.WLB) .   Also,  this  code  is  returned   if 
any  task  attempts  to  attach  a  mounted  volume. 

(continued  on  next  page) 
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Table  5-5   (Cont.) 
Disk  Status  Returns 


Cods 

Reason 

lE.SPC 

Illegal  address  space 

The  buffer  specified  for  a  read  or  write  request 
was  partially  or  totally  outside  the  address  space 
of  the  issuing  task.   Alternately,  a  byte  count  of 
0  was  specified. 

lE.VER 

Unrecoverable  error 

After  the  system's  standard  number  of   retries  has 
been  attempted   upon  encountering   an  error,  the 
operation  still  could  not  be  completed.   For   disk. 

unrecoverable  errors  are  usually  parity  errors. 

lE.WCK 

Write  check  error 

An   error   was  detected  during   the  write  check 

portion  of  an  operation. 

lE.WLK 

Write-locked  device 

The  task  attempted  to  write   on   a   disk   that   was 
write-locked. 

When  a  disk  I/O  error  condition  is  detected,  an  error  is  usually  not 
returned  immediately.  Instead,  RSX-llM  attempts  to  recover  from  most 
errors  by  retrying  the  function  as  many  as  eight  times.  Unrecoverable 
errors  are  generally  parity,  timing,  or  other  errors  caused  by  a 
hardware  malfunction. 


5.5   PROGRAMMING  HINTS 


For  the  RK611  controller/RK06  or  RK07  disk,  the  RLll  controller/RLOl 
or  RL02  disk,  RM02  disk,  RM03  disk,  RM05  disk,  RM80  disk,  and  RP07 
disk,  the  driver  write-protects  the  last  track  of  the  cartridge.  This 
track  contains  the  factory-recorded  bad-sector  file. 
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DBCTAPB  DRIVER 


6.1   INTRODUCTION 

The  RSX-llM  DECtape  driver  supports  the  TCll-G  dual  DECtape  controller 
with  up  to  three  additional  dual  DECtape  transports.  The  TCll-G  is  a 
dual-unit,  bidirectional,  hiagnetic-tape  transport  system  for  auxiliary 
data  storage.  DECtape  is  formatted  to  store  data  at  fixed  positions 
on  the  tape,  rather  than  at  unknovm  or  variable  positions  as  on 
coventional  magnetic  tape.  The  system  uses  redundant  recording  of  the 
mark,  timing,  and  data  trai.'ks  to  increase  reliability.  Each  reel 
contains  578  logical  blocks.  As  with  disk,  each  of  these  blocks  can 
be  accessed  separately,  and  each  contains  256  words. 


6.2   GET  LUN  INFORMATION  MACRO 

Word  2  of  the  buffer  filled  by  the  Get  LUN  Information  system 
directive  (the  first  characterics  w«,  rd)  contains  the  following 
information  for  DECtapes.  A  bit  setting  of  1  indicates  that  the 
described  characteristic  is  true  for  DECtapes. 

Bit    Setting  Meaning 

0  0  Record-oriented  device 

1  0  Carriage-control  device 

2  0  Terminal  device 

3  1  File  structured  device 

4  0  Single-directory  device 

5  0  Sequential  device 

6  1  Mass  storage  device 

7  0  User-mode  diagnostics  supported 

8  0  Device  supports  22-bit  addressing 

9  0  Unit  software  write-locked 
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Bt 

1 
1 
1 
1 

2 

1 

Words  3 
the  def 


Batting  Meaning 

0        Input  spooled  device 
0        Output  spooled  device 
0        Pseudo  device 

0  Device  mountable  as  a  communications 
channel 

1  Device  mountable  as  a  FILES-11  volume 

1        Device  mountable 

and  4  of  the  buffer  contain  the  maximum  LBN.  Word  5  indicates 
ult  buffer  size,  512  bytes,  for  DECtape. 


6.3   QIO  MACRO 

This  section  summarizes  standard  and  device-specific  QIC  functions  for 
the  DECtape  driver. 


6.3.1  Standard  QIO  Functions 

Table  6-1  lists  the  standard  functions  of  the  QIO  macro  that  are  valid 
for  DECtape. 


Table  6-1 
Standard  QIO  Functions  for  DECtape 


Format 

Function 

QIOSC 

10. ATT, . . . 

Attach  device^ 

giosc 

lO.DET,... 

Detach  device 

QIOSC 

lO.KIL,... 

Kill  I/o2 

QIOSC 

lO.RLB, .. . ,<stadd,size. 

,,lbn> 

READ  logical  block  (forward) 

QIOSC 

lO.RVB,... ,<stadd,size. 

,,lbn> 

READ  virtual  block  (forward) 

QIOSC 

lO.WLB, . . . ,<stadd,size. 

,,lbn> 

WRITE  logical  block  (forward) 

QIOSC 

IO.WVB,...,<stadd,size, 

,,lbn> 

WRITE  virtual  block  (forward) 

1.  Only  unmounted  volumes  may  be  attached.  An  attempt  to  attach  a 
mounted  volume  will  result  in  an  lE.PRI  status  being  returned  in  the 
I/O  status  doubleword. 

2.  In-progr«ss  DECtape  operations  are  allowed  to  complete  when 
lO.KIL  is  received,  unless  the  unit  is  not  ready,  because  they  take 
such  a  short  time.  I/O  requests  that  are  queued  when  lO.KIL  is 
received  are  killed.  An  IE. ABO  status  is  returned  in  the  I/O  status 
doubleword. 
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■tadd 


Th«  starting  addraas  of  tha  data  buffar   (must  ba  on  a  irard 
boundary) . 


alia 


Ibn 


Tha  data  buffar  aiza  in   bytas  (muat  ba  avan  and  graatar  than  0) 


The  logical  block  number  on  the  DECtape  where  the  transfer  starts 
(must  be  in  the  range  0-577) . 


lO.RVB  and  lO.WVB  are  associated  with  file  operations  (see  the 
IAS/RSX-11  I/O  Operations  Reference  Manjal) .  For  these  functions  to 
be  executed,  a  file  must  be  open  on  the  specified  LUN  if  the  volume 
associated  with  the  LUN  is  mounted.  Otherwise,  the  virtual  I/O 
reques|^  is  converted  to  a  logical  I/O  request  using  the  specified 
block  numbers. 


6.3.2  Davlce-Spacif ic  QIO  Functions 

The  device-specific  functions  of  the  QIO  macro   that  are  valid   for 
DECtape  are  shown  in  Table  6-2. 


Table  6-2 
Device-Specific  Functions  for  DECtape 


Format 

Function 

QIOSC  lO.RLV,... ,<stadd,slze,, ,lbn> 
QIO$C  lO.WLV,... ,<stadd,size,,,lbn> 

READ  logical  block  (reverse) 
WRITE  logical  block  (reverse) 

stadd 


The  starting  address  of  the  data   buffer   (must  be  on   a  word 
boundary) . 


size 


Ibn 


The  data  buffer  size  In  bytes  (must  be  even  and  greater  than  0) . 


The  transfer  starts  (must  be  in  the  range  0-577) . 


,-..-i;,-/ . 
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«>.4   STATUS  RETURNS 

Th«  arror  and  status  conditions  listed  in  Tabic  6-3  arc   raturnad   by 
the  DECtapa  driver  described  in  this  chapter. 


Table  6-3 
DECtape  Status  Returns 


Code 


Reason 


IS. sue 


IS.PND 


IE. ABO 


lE.ALN 


lE.BLK 


IE. BYT 


lE.DNR 


IE. IPC 


Successful  completion 

The  operation  specified  in  the  010  directive  was 
completed  successfully.  The  second  word  of  the  I/O 
status  block  can  be  examined  to  determine  the 
number  of  bytes  processed,  if  the  operation 
involved  reading  or  writing. 

I/O  request  pending 

The  operation  specified  in  the  QIO  directive  has 
not  yet  been  executed.  The  I/O  status  block  is 
filled  with  Os. 

Request  aborted 

An  I/O  request  was  queued  (not  yet  acted  upon  by 
the  driver)  when  an  lO.KIL  was  issued. 

File  already  9P«n 

The  task  attempted  to  open  a  file  on  the  physical 
device  unit  apsoctated  with  the  specified  LUN,  but 
a  file  has  already  been  opened  by  the  issuing  task 
on  that  LUN. 

Illegal  block  number 

An  illegal  logical  block  number  was  specified  for 
DECtape.   The  number  exceeds  577  (1101  (8)). 

Byte-aligned  buffer  specified 

Byte  alignment  was  specified  for  a  buffer,  but  only 
word  alignment  is  legal  for  DECtape.  Alternately, 
the  length  of  the  buffer  is  not  an  even  number  of 
bytes. 

Device  not  ready 

The  physical  device  unit  specified  in  the  QIO 
directive  was  not  ready  to  perform  the  desired  I/O 
operation. 

Illegal  function 

A  function  code  was  specified  in  an  I/O  request 
that  is  illegal  for  DECtape. 


(continued  on  next  page) 
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lE.NLN 


IE. NOD 


lE.OPL 


lE.OVR 


lE.PRI 


lE.SPC 
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Tabl*  6-3   (Cont.) 
DECtap*  Status  Returns 


Reason 


Pile  not  open 

The  task  attempted  to  close  a  file  on  the  physical 
device  unit  associated  with  the  specified  LUN,  but 
no  file  was  currently  open  on  that  LUN. 

Insufficient  buffer  space 

Dynamic  storage  space  has  been  depleted,  and  there 
was  insufficient  buffer  space  available  to  allocate 
a  secondary  control  block.  For  example,  if  a  task 
attempts  to  open  a  file,  buffer  space  for  the 
window  and  file  control  block  mu3t  be  supplied  by 
the  Executive.  This  code  is  returned  when  there  is 
not  enough  space  for  this  operation. 

Device  off  1 ine 

The  physical  device  unit  associated  with  the  LUN 
specified  in  the  QIO  directive  was  not  on  line. 
When  the  system  was  booted,  a  device  check 
indicated  that  this  physical  device  unit  was  not  in 
the  configuration. 

Illegal  read  overlay  request 

A  read  overlay  was  requested  and  th<e  physical 
device  unit  specified  in  the  QIO  directive  was  not 
the  physical  device  unit  from  which  the  task  was 
installed.  The  read  overlay  function  can  only  be 
executed  on  the  physical  device  unit  from  which  the 
task  image  containing  the  overlays  was  installed. 

Privilege  violation 

The  task  that  issued  the  request  was  not  privileged 
to  execute  that  request.  For  DECtape,  this  code  is 
returned  when  a  nonpr ivileged  task  attempts  to  read 
or  write  a  mounted  volume  directly  (that  is, 
lO.RLB,  lO.RLV,  lO.WLB,  or  lO.WLV) .  Also,  this 
code  is  returned  if  any  task  attempts  to  attach  a 
mounted  volume. 

Illegal  address  space 

The  buffer  specified  for  a  read  or  write  request 
was  partially  or  totally  outside  the  address  space 
of  the  issuing  task.  Alternately,  a  byte  count  of 
0  was  specified. 


(continued  on  next  page) 
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TabM  6-3   (Cont.) 
DECtap*  Status  Returns 


Coda 

Raason 

lE.VER 

Unraro^arahla  arror 

Aftar  tha  systam's  standard  numbar  of   ratrias  has 
baan   attemptad   upon   ancountarlng   an   error,  the 
oporation   still   could   not   be  completed.     For 
DECtapc,   this  code  la  returned  to  indicate  any  of 
tha  following  conditions. 

•   A  parity  error  was  encountered. 

•   The  task  attanpted  a  forward  multiblock  transfer 
past  block  577  (1101  (8)). 

a   The   task  attempted   a   backward   multiblock 
transfer  past  block  0. 

lE.WLK 

Write-locked  device 

Tha  task  attempted  to  write  on  a  DECtape  unit   that 
was  physically  write-locked. 

't.4.1  DECtape  Recovery  Procedures 

When  a  DECtape  I/O  error  condition  is  detected,  RSX-llM  attempts  to 
recover  from  the  condition  by  retrying  the  function  as  many  as  five 
times.  Unrecoverable  errors  are  generally  parity,  mark  track,  or 
other  errors  caused  by  a  faulty  recording  medium  or  a  hardware 
malfunction.  An  uncecoverable  error  condition  also  occurs  when  a  read 
or  write  operation  is  performed  past  the  last  block  of  the  DECtape  on 
a  forward  operation,  »■.'  the  first  block  of  the  DECtape  on  a  reverse 
operation. 


In  addition  to  the  standard  error  conditions,  an  unrecoverable  error 
is  reported  when  the  "rock  count"  exceeds  8.  The  rock  count  is  the 
number  of  tines  the  DECtape  driver  reverses  the  direction  of  the  tape 
while  looking  for  a  block  number.  Assume  that  the  block  numbers  on  a 
portion  of  DECtape  are  99,  96,  and  101,  where  one  bit  was  dropped  from 
block  number  100,  making  it  96.  if  an  I/O  request  is  received  for 
block  100  and  the  tape  is  positioned  at  block  99,  the  driver  starts 
searching  forward  for  block  100.  The  first  block  to  be  encountered  is 
96  and,  because  the  driver  is  searching  for  block  100  in  a  forward 
direction  and  96  is  less  than  100,  the  search  continues  forward. 
Block  101  is  the  next  block  and,  because  number  101  is  greater  than 
100,  the  driver  reverses  the  direction  of  the  tape  and  starts  to 
search  backward.  The  next  block  number  in  this  direction  is  9€,  and 
the  direction  is  reversed  again  because  100  is  greater  than  96.  To 
prevent  the  DECtape  from  being  hung  in  this  position,  continually 
rocking  between  block  numbers  96  and  100,  a  maximum  rock  count  of  8 
has  been  established. 
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6.4.2  S«l«ct  Recovery 

If  th«  DECtap«  unit  Is  in  an  oft-line  condition  when  the  I/O  function 
is  performed,  the  message  shown  below  is  output  on  the  operatcr'n 
cop.aole. 

••*  DTnj   --  SELECT  ERROR 

where  n  is  the  unit  number  of  the  drive  that  is  currently  off  line. 
The  user  should  respond  by  placing  the  unit  to  REMOTE.  The  driver 
retries  the  function,  fron  the  beginning,  once  every  second.  It 
displays  the  message  once  every  15  seconds  until  the  appropriate 
DECtapr  unit  is  selected.  A  select  error  may  also  occur  when  there 
are  two  drives  with  the  same  unit  number  or  when  no  drive  has  the 
appropriate  unit  number. 


6.5   PROGRAMMING  HINTS 

This  section  contains  information  on  important  programif.ing 
considerations  relevant  to  users  of  the  DECtape  driver  described  in 
this  chapter. 


6.5.1   DECtape  Transfers 

If  the  transfer  length  on  a  write  is  less  than  256  words,  a  partial 
block  is  transferred  with  zero  fill  for  the  rest  of  the  physical 
block.  If  the  transfer  length  on  a  read  is  less  than  256  words,  only 
tiie  number  of  words  specified  is  transferred.  If  the  transfer  length 
is  greater  than  256  words,  more  than  one  physical  block  is 
transferred. 


6.5.2   Reverse  Reading  and  Writing 

The  DECtape  driver  supports  reverse  reading  and  writing,  because  these 
functions  speec"  up  data  transfers  in  some  cases.  A  b^ock  should 
normally  be  read  in  the  same  direction  in  which  it  was  written.  If  a 
block  is  road  from  a  DECtape  into  memory  in  the  opposite  direction 
from  that  in  which  it  was  written,  it  is  reversed  in  memory  (for 
example,  word  255  becomes  word  0,  and  254  becomes  word  1)„  If  this 
occurs,  the  user  must  then  reverse  the  data  within  memory. 


6.5.3  Speed  Considerations  When  Reversing  Direction 

It  is  possible  to  reverse  direction  at  any  time  while  reading  or 
writing  DECtape.  However,  the  user  should  understand  that  reversing 
direction  substantially  slows  down  the  movement  of  the  t^pe.  Because 
DECtape  must  be  moving  at  a  certain  minimum  speed  before  reading  or 
writing  can  be  performed,  a  tape  block  cannot  be  accessed  immediately 
after  reversing  direction.  Two  blocks  must  be  bypassed  before  a  read 
or  write  function  can  be  e>:ecuted,  to  give  the  tape  unit  time  to  build 
up  to  normal  access  speed.  Furthermore,  when  a  request  is  issued  to 
read  or  write  in  a  certain  direction,  the  tape  first  begins  to  move  in 
that  dire(.tion,  then  starts  detecting  block  numbers.  The  following 
examples  illustrate  chese  principles. 
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If  «  DBCtap*  is  positioned  at  block  number  12  and  the  driver  receives 
a  request  to  read  bluck  10  forward,  the  tape  starts  to  move  forward, 
in  the  direction  requested.  When  block  number  14  is"'encourtered,  the 
driver  reverses  the  direction  of  the  tape,  since  14  is  greater  than 
10.  The  search  continues  backward,  and  Mock  numbers  11  and  10  are 
encountered.  Because  the  direction  must  be  reversed  and  the  driver 
requires  two  blocks  to  build  up  sufficient  speed  for  reading,  block 
number  9  and  6  are  also  bypassed  in  the  backward  direction.  Then  the 
direction  is  reversed  and  the  driver  encounters  blocks  8  and  9  forward 
before  reaching  block  number  10  and  executing  the  read  request. 


K.S.4  Aborting  a  Task 

If  a  task  is  aborted  while  waiting  for  a   umt   to  be  selected,   the 
DECtape  driver  recognizes  this  fact  within  1  second. 


CHAPTER  7 
DBCTAPE  II  DRIVER 


7 . 1   INTRODUCTION 

The  DECTAPE  II  (TU58)  driver  supports  TU58  system  hardware,   providing 
low-cost,  block-replaceable  mass  storage. 


7.1.1  TU58  Hardware 

Each  TU58  DECTAPE  II  system  consists  of  one  or  two  TU58  cartridge 
drives,  one  tape  drive  controller,  and  one  DLll-type  serial  line 
interface.  Each  TU58  drive  functions  as  a  random  access, 
block-formatted  mass  storage  device.  Each  tape  cartridge  is  capable 
of  storing  512(10)  blocks  of  512(10)  bytes  each.  Access  time  averages 
10  seconds.  All  I/O  transfers  (commands  and  data)  occur  by  means  of 
the  serial  line  interface  at  serial  transmission  rates  of  9600  bps. 
All  read  and  write  check  operations  are  performed  by  the  controller 
hardware  using  a  16-bit  checksum.  The  controller  performs  up  to  eight 
attempts  to  read  a  block,  as  necessary,  before  aborting  the  read 
operation  and  returning  a  hard  error;  however,  whenever  more  than  one 
read  attempt  is  required  for  a  successful  read,  the  driver  is  notified 
in  order  to  report  a  soft  error  message  to  the  error  logger. 


7.1.2  TU58  Driver 

The  TU58  driver  communicates  with  the  TU58  hardware  by  means  of  a 
serial  xine  interface  (DLll);  no  other  interface  is  required.  All 
data  and  command  transfers  between  the  PDP-11  system  and  the  TU58  are 
done  with  programmed  I/O  and  interrupt-driven  routin'^s;  NPRs  are  not 
supported. 


7.2   GET  LUN  INFORMATION  MACRO 

Word  2  of  the  buffer  filled  by  the  Get  LUN  Information  system 
directive  (the  first  characteristics  word)  contains  the  following 
information  for  the  TU58.  A  bit  setting  of  1  indicates  that  the 
described  characteristic  is  true  for  this  device. 
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Meaning 

R«cord-orl«nt«d  device 

Carri«9«-control  device 

Terminal  device 

Pile-structured  device 

Single-directory  device 

Sequential  device 

Mass  storage  device 

User-mode  diagnostics  supported 

Device  supports  22-bit  direct  addressing 

l*nit  software  wrlte-locked 

Input  spooled  device 

Output  spooled  device 

Pseudo  device         , 

Device  mountable  as  a  communications  channel 

Device  mountable  as  a  FILES-11  volume 

Device  mountable 

Words  3  and  4  of  the  buffer  are  a  double-precision  number  specifying 
the  total  number  of  blocks  on  the  device;  this  value  is  512(10) 
blocks.  Word  5  ind'^ates  the  default  bul!fer  size,  which  is  512(10) 
bytes. 

* 

7.3   QIO  MACRO 

This  section  summarizes  standard  and  device-specific  QIO  functions  for 
the  TU58. 

7.3.1  Standard  QIO  Functions 

Table  7-1  lists  the  standard  OIO  system  directive  functions  of  the  QIO 
macro  that  are  valid  Cor  the  TU58. 


tit 
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1 

1 
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11 
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Table  7-1 
Standard  QIO  7unction8  for  tha  TOSS 


Koraat 

Function 

0IO8C 

10. ATT, . . . 

Attach  device 

OIOSC 

lO.DET,... 

Detach  device 

oiosc 

lO.KIL,... 

Cancel  I/O  requests^ 

OIOSC 

I0.RLB,...,<8tadd,siz«, 

,,lbn> 

READ  logical  block 

OIOSC 

lO.WLO, . . . ,<stadd,8ize. 

, ,lbn> 

WRITE  logical  block 

1.  In-progress  operations  are  allowed  to  conplete  when  lO.KIL 
i&  received.  I/O  requests  that  are  queued  when  lO.KIL  is 
received  are  killed. 


■tadd 


size 


Ibn 


The  starting  address  of  the   data   buffer   (must   be  on   a   word 
boundary) . 


The  data  buffer  size  in  bytes  (must  be  even  and  greater  than  0). 


The  logical  block  number  on  the  cartridge   tape  where   the  data 
transfer  starts  (must  be  in  the  range  of  0-777) . 


7.3.2  Device-Specific  QIO  Functions 

The  device-specific  QIO  system  directive  functions  that  are  vall>:1   for 
the  TU58  are  shown  in  Table  7-2. 


Table  7-2 
Device-Specific  QIO  Functions  for  the  TUS8 


Format 

Function 

OIOSC  lO.WLC, . . . ,<stadd,size, , , ,lbn> 
QIGSC  IO.RLC,...,<stadd,size, , , ,lbn> 
OIOSC  IO.BLS!I0.UMD,...,<lbn> 
OIOSC  lO.DGNIIQ.UMD,... 

WRITE  logical  block  with  check 
READ  logical  block  with  check 
POSITION  tape 
Run  internal  diagnostics 
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■tadd 

The  starting  address  of  the  data  buffer   (must  be  on  a  word 
boundary) . 


aiz« 


Ibn 


The  data  buffer  size  in  bytes  (must  be  even  and  greater  than  0) 


The  logical  block  number  on  the  cartridge  tape  where  the  data 
transfer  starts  (must  be  in  the  range  of  0-777) . 

Additional  details  for  device-specific  010  functions  are   provided   in 
the  following  paragraphs. 


7.3.2.1  lO.WLC  -  The  lO.WLC  function  writes  the  specified  data  onto 
the  tape  cartridge.  A  checksum  verification  is  then  performed  by 
reading  the  data  just  written;  data  is  not  returned  to  the  task 
issuing  the  function.  An  appropriate  status,  based  on  the  checksum 
verification,  is  returned  to  the  issuing  task. 


7.3.2.2  lO.RLC  -  The  lO.RLC  function  reads  the  tape  witn  an  increased 
threshold  in  the  TU58's  data  recovery  circuit.  This  is  done  as  a 
check  to  insure  data  read  reliability. 


7.3.2.3  lO.BLS  -  The  lO.BLS  function  is  used  for  diagnostic  purposes 
to  position  the  tape  to  the  specified  logical  block  number.  If  you 
specify  lO.BLS,  you  must  use  the  IQ.UMD  subfunction  (see  Chapter  1). 


7.3.2.4  lO.DGN  -  The  lO.DGN  function  is  used  for  diagnostic  purposes 
to  execute  the  TU58's  Internal  (firmware)  diagnostics.  Appropriate 
status  Information  is  returned  to  the  issuing  task  by  the  I/O  status 
block.  If  you  specify  lO.DGN,  you  must  use  the  IQ.UMD  subfunction 
(see  Chapter  1) . 


7.4   STATUS  RETURNS 

Table  7-3  lists  the  error  and  status  conditions  that  are  returned  by 
the  TU58  driver. 
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Table  7-3 
TUS8  Driver  Status  Raturni 


Code 

Reason 

IS. sue 

Successful  completion 

The  operation  specified  In  the  QIO  directive  was 
completed  successfully.  The  second  word  of  the  I/O 
status  block  can  be  examined  to  determine  the  number  of 
bytes  processed,  if  the  operation  involved  reading  or 
writing . 

lEi.DNR 

Device  not  ready 

The  physical  device  unit  specified  in  the  QIO  directive 
was  not  ready  to  perform  the  desired  I/O  operation. 

IE. IPC 

Illegal  function 

A  function  code  was  specified  in  an  I/O  request  that  is 
illegal  for  the  TU58. 

lE.FHE 

Fatal  hardware  error 

lE.TMO 

Time-out  error 

1 

Tne  TU58  failed  to  respond  to  a  function  within  the 
normal  time  specified  by  the  driver. 

lE.VER 

Unrecoverable  error 

After  the  system's  standard  number  of  retries  (8)  has 
been  attempted  upon  encountering  an  error,  the  operation 
still  could  not  be  successfully  completed. 

lE.WLK 

Cartridge  write-locked 

The  task  attempted  to  write  on  a  tape  cartridge  that  is 
physically  write-locked. 
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8.1   INTRODOCriON 

RSX-llM  and  RSX-llM-PLUS  support  a  variety  of  magnetic  tape  devices. 
Table  8-1  summarizes  these  devices  and  subsequent  sections  describe 
them  in  greater  detail. 

Programming  fo;  magtape  is  quite  similar  to  programming  for  the 
magnetic  tape  cassette  (see  Chapter  9).  Unlike  cassette,  however, 
magtape  can  handle  variable-length  records  and  allows  the  user  to 
select  a  parity  mode. 


8.1.1  TE10/T010/TS03  Magnetic  Tape 

The  TE10/TU10/TS03  consists  of  a  TMll  controller  with  a  TEIO,  TUlO,  or 
TS03  transport.  It  is  a  low-cost,  high-performance  system  for  serial 
si.orage  of  large  volumes  olf  data  and  programs  in  an 
industry-compatible  format.  All  recording  is  nonreturn-to-zero, 
inverted  (NRZI) . 


8.1.2   TE16/T016/T045/T077/T078  Magnetic  Tape 

The  TE16/TU16/TU45/TU77/TU78  consistn  of  an  RH11/RH70  controller,  a 
TM02,  TM03,  or  TM78  formatter,  and  a  TE16/TU16/TU45/TU77/TU78 
transport.  They  are  quite  similar  to  the  TEIO/TUIO  but  are  Massbus 
devices,  with  a  common  controller,  a  specialized  formatter,  and 
drives.  Recording  JJ  either  800  bpi  NRZI  or  1600  bpi  phase-encoded 
(PE)  for  the  TE16/TU16/TU45/TU77.  Thj  TU78  records  in  1600  bpi 
phase-encoded  or  6250  bpi  OCR  modes. 


8.1.3  TS11/T080  Magnetic  Tape 

The  TSll  and  TtJSO  are  integrated  subsystemn.  Each  has  a  drive,  a 
controller,  and  a  formatter.  The  hardware  is  microprocessor 
controlled  for  all  operations,  including  I/O  transfers,  tape  motion, 
and  so  forth,  and  has  comprehensive  (internal)  diagnostic  test 
execution.   Recording  is  1600  bpi  phase-encoded  (PE) . 

The  TSll  operates  in  conventional  start  and  step  mode  while  the  TU80 
operates  at  either  low  speed  (start  and  stop  mode)  or  high  speed 
(streaming  mode) .   Tape  speed  is  microprocessor  controlled. 
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8.1.4   TSVOS  Nagnatic  Tap* 

Tha  TSVOS  tapa  aubayatam  la  a  Q  BUS   davlca.  It   la   an   intagcatad 

aubayatam  with   a  drlva,  a  controllar,  and  a  focmattar.   Tha  hardwara 
ia  microprocaaaor   controllad   foe   all   opacatlona.   Including    I/O 

tcanafara,   tapa  notion,  and  ao  forth  and  haa  cooiprehenai va  (intarnal) 

diagnoatlc  taat  axacution.   Racording  ia  1600  bpi  phaaa-ancodad   (PB) . 
Tha  TSV05  oparataa  at  25  inchaa  par  aacond. 


Tabla  8-1 
Standard  Magtapa  Davicaa 


Davicaa 

Channala 

Heeordlnf  Danalty 
(Praaea/Inch) 

Tapa  Spaad 

( Inchaa/aacond) 

Nailaua  Data 
Tranafar  Rata 
(•ytaa/Sacond) 

Racording 
Nathod 

niO.TOlO 

t 

7  or 

(TIIO) 
f  (TOlO) 

For  7-ehann«li 

200.  SS6.  or 

■00 

Pet  9-ehannali 

•00 

4S 

36.000 

■RII 

TBl«,m« 

• 

•00  or  1600 

4S 

For  600  bpi I 

16,000 

For  1600  bpi: 

72,000 

MRU  or 

Fhaaa 
■ncodlnq 

na 

• 

too  or  1600 

75 

For  600  bplt 

60,000 

For  1600  bpi : 

120,000 

HRii  or 
Fhaaa 

■ncodlnq 

t077 

9 

(00  or  1600 

12S 

For  aOO  bpi I 

100,000 

For  1600  bpi: 

200.000 

NRII  or 

Fhaaa 
•need  1  nq 

Ta03 

• 

•00 

u 

12.000 

HRtI 

nil 

< 

1600 

4t 

72.000 

Fhaaa  Incodlng 

«>7i 

» 

1600  or  62S0 

125 

For  1600  bpi: 

200.000 

For  6250  bv>l: 

711.000 

Fhaaa  Incodinq 
or  OCR  (Group 
Cyclical 
Record Inq) 

nio 

» 

1600 

251 
100> 

«o,oooi 

160,000^ 

Fhaaa  Bncodlng 

n<n% 

• 

1600 

at 

40,000 

Fhaaa  Raced Ing 

1.  Lew  Speed 

2.  High  Speed 
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8.2   GET  LDN  IMrORHATION  HACRO 

Word  2  of  the  buffer  filled  by  the  Get  LUN  Information  ■ystein 
directive  (the  first  characteristics  word)  contains  the  following 
information  for  magtapes.  A  bit  setting  of  1  indicates  that  the 
described  characteristic  is  true  for  magtapes. 


Words 
defaul 


Setting  Meaning 

0  or  1  Record-oriented  device  (0  if  the  tape  is 
mounted,  1  if  it  is  not) 

0         Carriage-control  device 

0         Terminal  device 

0         File-atructured  device 

0  or  I    Single-directory  device  (0  if  the  tape  is  not 

mounted,  1  if  it  is) 

1  Sequential  device 

1         Mass  storage  device 

0  or  1    User-mode  diagnostics  supported^ 

0  or  1  Massbus  device  (set  only  for  TE16,  TU16, 
TU45,  TU7V,  or  TU78  drives  interfaced  by 
means  of  an  RH70  controller)^ 

0  Unit  software  write-locked 

0  Input  spooled  device  ^ 

0  Output  spooled  device 

0  Pseudo  device 

0         Device  mountable  as  a  communications 
channel  ^ 

0  or  I    Device  mountable  as  a  FILES-11  volume^ 

0  or  1    Device  mountable^ 


and  4  of  the  buffer   are   undefined;    word   5   indicates   the 
buffer  size,  for  magtapes  512  bytes. 


8.3   QIO  MACRO 

This  section  summarizes  standard  and  device-specific  QIO  functions  for 
the  magtape  drivers. 


1.  SYSGEN  and  device-dependent  characteristic. 
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1,3.1  Standard  QIO  runctlona 

Tabla  8-2  liata  tha  atandard  functlona  of  tha  QIO  macro  that  ara  valid 
for  fflagtapa. 


Tabla  8-2 
Stcn'lard  QIO  Punctiona  for  Magtapa 


Fornat 

Function 

QIO$C 

10. ATT,... 

Attach  davica 

QIO$C 

lO.DET, . . . 

Datach  davica 

QIO$C 

lO.KIL,... 

Cancal  I/O  requaats 

QIO$C 

lO.RLB, . . . ,<stadd,size> 

READ  logical  block 
(read  tape  into  buffer) 

q:o$c 

lO.RVB, . . . ,<atadd,8ize> 

READ  virtual  block 
(read  tape  into  buffer) 

QIO$C 

lO.WLB, . . . ,<stadd,8lze> 

WRITE  logical  block 
(write  buffer  contenta  to 

tape) 

QIO$C 

lO.WVB, . . . ,<stadd,8ize> 

WRITE  virtual  block 
(write  buffer  contents  to 

tape) 

• 


■tadd 


The  starting  address  oi  the  data  buffer   (muat  be  on  a  word 
boundary) . 


ait.  .y,^  ..'.•••, 

The  data  buffer  size  in  bytes.   Size  must  be  even,  greater  than 
0,  and,  for  a  write,  must  be  at  least  14  bytes. 

lO.KiL  does  not  cancel  an  in  progress  request  unless  a  select  error 
hac  occurred. 


8.3.2  Device-Specific  QIO  Punctiona 

Table  8-3  lists  the  device-specific  functions  of  the  QIO  macro  that 
are  valid  for  magtape.  Additional  details  on  certain  functions  appear 
below. 


8.3,2.1  lO.RLV  -  The  data  appears  in  the  specified  buffer  in  a 
fashion  identical  with  lO.RLB  or  lO.RVB,  as  long  as  the  data  block  has 
the  same  length  as  the  buffer. 
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1.3.2.2  lO.miD  -  CoMplation  of  lO.RMD  maans  that  th«  rewind  ha«  b««n 
initiated.  Additional  op*catlon«  on  that  contcollar  may  then  b« 
qu«u*d.  Howvvec ,  a  request  for  the  sane  unit  will  be  queued  b^  the 
driver  until  load  point  (BOT)  is  reached. 


8.3.2.3  lO.nrO  -  lO.RWU  is  normally  used  when  operator  intervention 
is  required  (for  example,  to  load  a  new  tape).  The  operator  must  turn 
the  unit  back  on  line  manually  before  subsequent  operations  can 
proceed. 


Table  8-3 
Device-Specific  QIO  Functions  for  Magtape 


Format 

Function 

QI08C  lO.DSE,... 

Data  Security  Erase  (TU78  only) 

QIO$C  10. EOF,... 

Write  end-of-file  mark  (tape  mark) 

OIOSC  lO.ERS,... 

Erase  (TEiO  and  TUlO  not 
supported) 

QIOSC  I0.RLV,...,<8tadd,size> 

READ  logical  block  reverse  (TEIO 
and  TUlO  not  supported.) 

QI0$C  lO.RWD,... 

Rewind  unit 

0IO$C  lO.RWU,... 

Rewind  and  turn  unit  off  line 

C»I0$C  lO.SEC,... 

Sense  tape  characteristics 

QI0$C  I0.SN0,...,<cb> 

MOUNT  tape  and  set  tape 
characteristics  (Unit  must  be 
READY,  tape  at  LOAD  POINT.) 

QI0$C  lO.SPB,... ,<nb8> 

SPACE  blocks 

QI0$C  I0.SPF,...,<nes> 

SPACE  files 

QI0$C  I0.STC,...,<cb> 

SET  tape  characteristics 

nba 


The  characteristic  bits  to  set 


The  number  of   blocks   tr   space   past   (positive   if   forward, 
negative  if  reverse) . 
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Th«  nuabar  of  BOP  marks  to  spac*  past   (poaltlv*  if  focwacd, 
n*gativ«  If  ravaraa) . 


■ls« 


The  ail*  of  tha  stadd  data  buffer  in  bytaa   (muat  be  an  even 
number  of  bytes  greater  than  0) . 


■tadd 


The  starting  address  of  the  data  buffer   (may  be  on  a  byte 
boundary) . 


8.3.2.4  10. IRS  -  Erases  3  inches  of  (write  blank)  tape,  effectively 
providing  an  extended  interrecord  gap.  (Not  supported  on  TUlO  and 
TEIO.) 

> 

8.3.2.5  lO.DSI  -  The  TU78  will  erase  from  the  current  position  to 
•nd-of-tape  and  then  rewind  the  tape  to  beginning-of-tape. 


8.3.2.6   10. SBC  -  This  function  returns  the   tape  characteristics   in 

the  second  I/O  status  word.   The  tape  characteristic  bits  are  defined 

as  follows: 

■■  <  , 

Can  Be  Set  by 
Bit  Meaning  When  Set  lO.SMO  and  lO.STC 

/ 

0  For  TUlO,  556  bpi  •  X 
density  (7-channel) . 

For  TE16,  TU16,  TU45,  TU"/7, 

TU78,  and  TSll,  reserved.         ^ 

1  For  TUlO,  200  bpi  X 
density  (7-channel). 

For  TE16,  TU16,  TU45,  TU77,  and 
TU78,  reserved. 

For  TSll,  TU80,  and  TSV05,      'v 
swap  byte  mode  (read/write). 

2  For  TUlO,  core-dump  S 
mode  (7-channel,  see  below). 

.    _      For  TE16,  TU16,  TSll,  TU45, 
TU77,  and  TU78  reserved. 


* 


3  Even  parity  (default  is  odd) . 
(Not  selectable  for  the  TSll.) 

4  Tape  is  past  EOT. 

5  Last  tape  command  encountered 
EOF  (unless  last  command  was 
backspace) . 
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■it 


Nttanlng  Whan  8«t 


Can  Ba  Sat  by 
I0.8N0  and  I0.8TC 


6  Writing  ia  prohibitad. 

7  Writing  with  axtandad  intar- 
racoL'd  gap  ia  prohibitad 

(that  ia,  no  racovery  ia  attamptad 
aftar  writa  arror) . 

8  Salact  arror  on  unit. 

9  Unit  ia  rewinding. 

10  Tape  is  phyaically  wr i te-lockad . 

11  Por  TEIO,  TUlO,  and  TS03,  reserved. 
For  all  other  tapes,  1600  bpi  density. 

12  Por  TUlO,  drive  ia  7-channel. 
Por  all  other  tapes,  reserved. 

13  Tape  is  at  load  point  (BOT) . 

M)      Tape  ia  at  end-of- volume  (EOV) . 

%$'  Tape  is  past  EOV  (reaerved  for  dri- 

ver; always  0  when  read  by  user). 


I 


In  core-dump  mode  (TUlO  only,  800  bpi  density,  and  7-channel) ,  each 
8-bit  byte  is  written  on  2  tape  framea,  4  bits  per  frame.  In  other 
modes  on  7-channel  tape,  only  6  low-order  bits  per  byte  are  written. 

Por  the  TSll,  1600  bpi  density  is  always  selected  (bit  11-1).  Bit  11 
cannot  be  modified  by  either  the  lO.SMO  or  lO.STC  functions.  Por 
drives  that  use  the  TM03  controller,  this  bit  can  be  either  set  or 
cleared;  however,  once  the  tape  is  moved  from  the  load  (beginning  of 
tape)  position  (BOT),  the  device  driver  modifies  this  bit  to  reflect 
the  actual  density  of  the  tape  currently  mounted.  You  cannot  change 
bit  11  once  the  tape  is  moved  beyond  BOT.  For  the  TU78,  bit  11  set 
indicates  1600  bpi  and  bit  11  clear  indicates  6250  bpi.  Bit  11  cannot 
be  set  or  cleared  once  the  tape  is  moved  beyond  BOT. 

The  effect  of  these  settings  is  illustrated  in  Figure  8-1  for  the  TBIO 
and  TUlO,  and  in  Figure  8-2  for  the  TE16,  TU16,  TU45,  and  TU77. 


8-7 


April  1983 


HMRITIC   TAP!  DRIVBR8 


■TART 


SET  EVEN 
PABITY 


YES 


EVEN 
PARITY 

7 


SET  800  BPI 
NINE-CHANNEL 


YES 


SET  556  BPI 
SEVEN-CHANNEL 


YES 


NINE- 
CHANNEL 
TAPE 
7 


CORE 
DUMP 
MODE 

7 


556  BPI 


200  BPI 


SET  800  BPI 
SEVEN-CHANNEL 


YES 


YES 


SET  800  BPI 

JSEVENCHANNEL, 

CORE-DUMP 

MODE 


SET  200  BPI 
SEVEN-CHANNEL 


Figure  8-1   Determination  of  Tape  Characteristics  for  the  TEIO/TUIO 


■  t 
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SET  1600  BPt 


YES 


SET  800  BPI 


\           YES 

SET 

? 

EVEN  PARITY 

\^ 

\ 

ZK-003-ai 


Figure  8-2  Determination  of  Tape  Characteristics 
for  the  TE16/TU16/TU45/TU77 


8.3.2.7  lO.SMO  -  This  function  can  be  used  as  a  combination  of  the 
sense  (10. SEC)  and  set  (lO.STC)  tape  characteristics  functions. 
Unlike  lO.STC,  however,  the  lO.SMO  function  requires  that  the  unit  be 
READY  and  the  tape  be  at  load  point  (BOT) .  If  either  of  these 
conditions  is  not  met,  the  function  returns  an  error  status  code  of 
lE.FHE  (refer  to  Table  8-4). 

The  lO.SMO  function  should  be  used  to  set  the  characteristics  of  a 
newly  loaded  tape.  If  the  lE.FHE  error  code  is  returned,  the  tape 
drive  is  not  on  line  and  is  not  at  BOT. 
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8.4   STATUS  RETURNS 

The  trror  and  status  conditions  listed  in  Table  8-4  are  returned  by 
the  magtape  drivers  described  in  this  chapter. 


Code 


IS. sue 


IS.PND 


IE. ABO 


lE.BBE 


IE. BYT 


lE.DAA 


Table  8-4 
Magtape  Status  Returns 


Reason 


Successful  completion 


The  operation  specified  in  the   QIO 

completed  successfully.   The  second 

status  block   can   be  examined   to 

number   of   bytes   processed,   if 

Involved  reading  or  writing.    This 

returned   if  nbs  equals  0  In  an  lO.SPB  function  or 

if  nes  equals  0  in  an  lO.SPF  function. 


directive  was 
word  of  the  I/O 
determine  the 
the  operation 
code   is   also 


QIO  directive  has 
I/O  status  block  is 


I/O  request  pending 

The  operation  specified  in  the 
not   yet   been   completed.   The 
filled  with  Os. 

Operation  aborted 


The  specified  I/O  operation  was  canceled  by  lO.KIL 
while  in  progress  or  while  still  in  the  I/O  queue. 

Bad  block 

A  bad   block   was  encountered  while   reading   or 

writing   and  the  error  persists  after  nine  retries. 

The  number  of  bytes  transferred  Is  returned  in  the 
second   word   of   the   I/O  status  block.   For  TMll, 

lE.BBE  may  also  indicate   that  a   bad   tape   error 

(BTE)  has  been  encountered  while  reading  or 
spacing . 

> 

Byte-aligned  buffer  specified 

Byte  alignment  was  specified  for  a  buffer,  while 
only   word    alignment    is   legal   for   the   QIO. 

Alternatively,  the  length  of  a  buffer  is  not  an 
even  number  of  bytes. 

Device  already  attached 

The  physical  device  unit  specified  in  an  10. ATT 
function  was  already  attached  by  the  issuing  task. 
This  code  indicates  that  the  Issuing  task  has 
already  attached  the  desired  physical  device  unit, 
not  that  the  unit  was  attached  by  another  task. 


(continued  on  next  page) 
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Table  8-4   (Cont.) 
Magtape  Status  Returns 


Reason 


Data  overrun 

On  a  read,  a  record  exceeded  the  stated  buffer 
size.  The  final  portion  of  the  buffer  is  checked 
for  parity,  but  is  not  read  into  memory. 

Device  not  attached 

The  physical  device  unit  specified  in  an  lO.DET 
function  was  not  attached  by  the  issuing  task. 
This  code  has  no  bearing  on  the  attachment  status 
of  other  tasks. 

Device  not  ready 

The  physical  device  unit  specified  in  the  QIO 
directive  was  not  ready  to  perform  the  desired  I/O 
operation.  This  code  is  returned  to  indicate  one 
of  the  following  conditions: 

•  A  time-out  occurred  on  the  physical  device   unit 
(that  is,  an  interrupt  was  lost). 

•  A  vacuum  failure  occurred  on  the  magtape  drive. 

•  While   trying   to   read   or   space,   the  driver 
detected  blank  tape. 

•  The   LOAD  switch  on   the   physical   drive  was 
switchad  to  the  off  position. 

•  The  unit  failed  internal  diagnostic  tests   (TS04 
only) 

End-of-file  encountered 

An  end-of-file  (tapemark)  was  encountered. 

End-of-tape  encountered 

The  end-of-tape  (physical  end-of-volume)  was 
encountered  while  the  tape  was  moving  in  the 
forward  direction.  A  10-foot  length  of  tape  is 
provided  past  EOT  to  be  used  for  writing  data  and 
markers,  such  as  volume  trailer  labels.  The  IE. EOT 
code  will  continue  to  oe  returned  in  the  I/O  status 
block  until  the  EOT  marker  is  passed  In  the  reverse 
direction.  IE. EOT  is  not  returned  on  a  read 
operation. 


(continued  on  next  page) 
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Coda 


lE.EOV 


lE.FHE 


IE. IPC 


lE.OFL 


TE.SPC 


lE.VER 


lE.WLK 


Tabic  8-4   (Cont.) 
Magtape  Status  Returns 


Reason 


E.iJ-of-volume  encountered  (unlabeled  tape) 

On  a  forward  space  function,  the  logical 
end -of -volume  was  encountered.  An  end-of-volume  Is 
two  consecutive  end-of-file  marks  (EOF),  or  a 
beginning-of-tape  mark  (BOT)  followed  by  an  EOF. 
The  tape  is  normally  left  positioned  between  the 
two  marks. 

F^tal  hardware  error 

Nonrecoverable  hardware  malfunction:  e.g.,  magtape 
unit  not  READY  and/or  tape  not  at  LOAD  POINT  when 
lO.SMO  is  issued. 

Illegal  function 

An  illegal  function  (or  subfunctlon  bit)  vas 
specified  in  a  magtape  I/O  request.  Refer  also  to 
Section  8.4.3. 

Device  off  line  a 

The  physical  device  unit  araociated  with  the  LUN 
specified  in  the  QIO  directive  was  not  on  line. 
When  the  system  was  booted,  a  device  check 
indicated  that  this  physical  device  unit  was  not  in 
the  configuration. 

Illegal  address  space 

The  buffer  specified  for  a  read  or  write  request 
was  partially  or  totally  outside  the  address  ."oace 
of  the  issuing  task.  For  magtape,  this  code  is 
also  returned  if  a  byte  count  of  0  was  specified  or 
if  the  user  attempted  to  write  a  block  thi t  was 
less  than  14  bytes  long. 

Unrecoverable  error 

After  the  system's  standard  number  of  retries  has 
been  attempted  upon  encountering  an  error,  the 
operation  still  could  not  be  completed.  For 
magtape,  this  code  is  returned  in  the  case  of  CRC 
or  checksum  errors  or  when  a  tape  block  could  not 
be  read. 

Write-locked  device 

The  task  attempted  to  write  on  a  magtape  unit  that 
was  physically  write-locked.  Alternatively,  tape 
characteristic  bit  6  was  set  by  the  software  to 
write-lock  the  unit  logically. 
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After  procesaing  a  QIO  request,  the  magnetic  tape  c*river  returns  two 
status  words.  The  first  word  contain.!  one  of  the  I/O  status  codes 
listed  In  Table  tf-4. 

For  aucceaitful  QIO  execution  (IS.SUC)  or  read  requesta   (lE.DAO),  the 

second   I/O   status   word  may  contain   further   information.  The 

operations  for  which  thia  la  true,  and  the  information  returned,  are 
ahown  in  Table  H-5.   For  all  other  caaea  thia  word  ia  undefined. 


Table  8-5 
Information  Contained  in  the  Second  I/O  Status  Word 


I/O  Function  Code 

Information  Returned 

lO.RLB 
lO.RI.V 
lO.RVB 
10. SEC 
lO.SPB 
lO.SPF 
lO.WLB 
lO.WVB 

Number  of  bytes  transferred 
Number  of  bytes  transferred 
Number  of  bytes  transferred 
Tape  chara«:teristics  word 
Number  of  records  spaced  over 
Number  of  files  spaced  over 
Number  of  bytes  transferred 
Number  of  bytes  transferred 

8.4.1   Select  Recovery 

If  a  request  fails  because  the  desired  unit  is  off  line,  no  drive  has 
the  desired  unit  lumber,  ur  has  its  power  off,  the  following  message 
is  output  on  the  operator's  console: 

"**  MTn:  —  SELECT  ERPtR 


The  unit  number  of  the  specified  drive. 


■:; 


The  driver  checks  the  unit  for  readiness  and  repeats  the  message  every 
15  seconds  until  the  requesting  task  Is  aborted  or  the  unit  is  made 
available.  In  the  latter  case,  the  driver  then  proceeds  with  the 
request . 


8.4.2  Retry  Procedures  for  Reads  and  Writes 

If  an  error  occurs  during  a  read  (for  example,  vertical  parity  error)  , 
the  recovery  procedure  depends  on  the  type  of  magtape  In  use.  Read 
errors  for  TEIO,  TUlO,  TS03,  TE16,  TU16,  TU45,  TU77,  are  retried  by 
backspacing  one  record  and  then  rereading  the  record  In  question.  If 
the  error  persists  after  nine  retries,  lE.VER  Is  returned.  Read 
errors  for  the  TU78  are  retried  using  a  combination  of  backspacing  one 
record  and  then  rereading  the  record  In  question,  rereading  in  the 
opposite  direction,  rereading  at  both  normal/low  thresholds,  and 
cleaning  the  tape. 
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Raad  crrora  for  th«  TSll,  TU80,  and  TSV05  are  retirad  by  rereading  the 
block  In  error  a  predetermined  number  of  times.  Every  eighth  reread, 
the  block  is  passed  by  the  tape  cleaner  blade.  If  the  error  persists 
after  a  predetermined  number  of  retries,  lE.VBR  is  returned. 

Mrite  recovery  is  the  same  for  all  devices.  Wh^ii  a  write  operation 
fails,  the  driver  attempts  the  following  error  recovery  procedure: 

1.   Repositions  the  tape 


2.   Erases   three   inches   of   tape   (resulting   in  an 
interrecord  gap) 


extended 


3.   Retries  the  write  operation 

If  the  error  persists  after  a  predetermined  mmber  of  retries,   lE.VER 

is   returned.    The  requesting  task  can  use  lO.STC  to  prohibit  writing 

with  an   extended   interrecord   gap.    In  this   case,   the   tape   is 
backspaced  and  the  write  is  retried. 


8.4.3  Power-Fail  Recovary  for  Hagnetic  Tapes 

If  a  power  failure  and/or  loss  of  vacuum  occurs  on  a  magnetic  tape 
drive,  tape  position  is  lost.  (Note  that  an  initial  system  boot 
simulates  a  recovery  from  a  power  failure.)  Additionally,  on  auto-load 
drives,  the  tape  will  be  positioned  at  BOT  when  the  unit  is  turned  on 
line. 

To  prevent  accidental  destruction  of  data  currently  on  tape,  the 
driver  maintains  a  powei-fail  status  indicator.  When  this  indicator 
is  set,  the  driver  disallows  any  data  transfer  or  tape  motion  commands 
until  a  rewind  (lO.RWD),  rewind  unload  (lO.RWU),  or  mount  and  set 
characteristics  (lO.SMO)  function  is  issued.  These  functions  clear 
the  power-fail  indicator  and  allow  all  tape  functions  to  be  issued. 
It  is  also  possible  to  issue  the  set  and  sense  characteristics 
functions  (lO.STC  and  10. SEC)  while  the  power-fail  indicator  is  set. 
These  functions,  however,  will  not  clear  the  bit. 

All  functions  other  than  those  just  described  are  considered  illegal 
and  cause  the  return  of  the  lE.IFC  (illegal  function)  error  code  to 
the  requesting  task.  In  situations  where  a  tape  is  currently  a 
mounted  volume,  the  tape  should  be  dismounted  and  then  remounted 
before  use.  In  doing  this,  the  rewind  command  will  be  issued,  thereby 
clearing  th.'.'  power-fail  indicator. 


8.5   PROGRAMHING  HINTS 


This  section 
considerations 
chapter. 


contains    information   on    important   programming 
relevant  to  users  of  magtape  drivers  described  in  this 


8.5.1  Block  Size 

Each  block  must  contain  an  even  number  of  bytes,  at  lea  t  14  for  a 
write  and  at  most  65,534.  However,  tape  usage  is  more  efficient  with 
a  larger  buffer. 
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8.5.2  lapoc  mo*  of  R«««ttlng  Tap*  Chacactariatica 

A  task  that;  usaa  magtape  should  always  set  the  tape  charactcristica  to 
the  proper  va.ue  before  beginning  I/O  operations.  The  task  cannot  be 
certain  in  what  state  a  previous  task  left  these  characteristics.  It 
is  also  possible  that  an  operator  might  have  changed  the  magtape  unit 
selection.  If  the  selection  switch  is  changed,  the  new  physical 
device  unit  may  not  corrosponJ  to  the  characteristics  of  the  unit 
described  by  the  respective  unit  control  block. 


8.5.3  Aborting  a  Task 

If  a  task  is  aborted  while  waiting  for  a  magtape  unit  to 
the  magtape  driver  recognizes  this  fact  within  1  second. 


be  selected. 


If  a  task  is  aborted  while  waiting  for  a  magtape  unit  to  complete  a 
space  operation,  the  magtape  driver  may  allow  spacing  to  the  next  tape 
mark. 


8.5.4  Writing  an  Bven-Parity  Zero-NRZI 

If  an  even-parity  0  were  written  normally,  it  would  appear  to  the 
drive  as  blank  tape.  It  is  therefore  converted  to  20  (8).  If  this 
conversion  is  undesirable,  the  user  must  ensure  that  no  even-parity  Os 
are  output  on  the  tape. 


8.5.5  Density  Selection 

The  TM03  and  TM78  controllers  impose  the  following  density  selection 
restriction:  The  user  cannot  mix  recording  densities  on  any  volume 
associated  with  the  confoller. 

Density  for  write  operations  is  selected  when  the  tape  is  at  the  load 
(BOT)  position.  Density  for  read  operations  is  hardware  -  selected 
during  the  first  read  (away  from  BOT);  after  the  first  read,  the 
10. SEC  function  can  be  used  to  determine  (sense)  tape  density. 


8.5.6   End-of-Volume  Status  (Unlabeled  Tape) 

The  magnetic  tape  driver  detects  end-of-volume  when  it  spaces  over  the 
second  of  two  consecutive  tape  marks.  The  tape  is  left  positioned 
between  the  two  tape  marks. 


The  magnetic  tape  driver  returns  the  IE.  OV  status  code  only  on 
operations.   lE.EOV  is  never  returned  by  read  operations. 


space 


For  the  purpose  of  checking  for  end-of-volume,  the  driver  treats 
beginning  of  tape  (BOT)  as  a  tape  mark.  Therefore,  any  forward  space 
operation  from  BOT  that  immediately  encounters  a  tape  mark  will  return 
lE.EOV. 

If  a  space  operation  stops  between  two  tape  marks  but  does  not  space 
over  the  second  one,  the  driver  will  return  end  of  file  rather  than 
end-of-volume.  Any  subsequent  space  operation  from  this  point  that 
immediately  spaces  over  the  second  tape  mark  will  return 
end-of-volume.  . 
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During  lO.SPF  operations,  the  driver  considers  all  tape  marks  to  be 
files  except  for  BOT  and  for  the  second  tape  mark  spaced  over  at  the 
end  of  volume. 

Note  that  both  lO.SPF  and  lO.SPB  operations  leave  the  tape  positioned 
after  the  tape  mark  in  the  direction  of  travel. 

If  you  want  to  treat  two  consecutive  tape  marks  as  end-of-volume  on 
read  operations,  your  application  must  keep  track  of  the  tape  marks. 
The  magnetic  tape  driver  does  not  support  two  consecutive  tape  marks 
as  end-of-volume  on  read  operations. 


8.5.7  Resetting  VCK  Indicator 

When  the  tape  transport  status  for  a  TSll,  TU80,  or  TSV05  changes 
(goes  on-line  or  off-line) ,  further  I/O  operations  are  inhibited.  A 
deliberate  I/O  sequencing  must  occur  to  reset  the  VCK  indicator  and 
allow  physical  I/O  to  proceed.  This  sequencing  is  done  by  issuing  a 
lO.RWD  or  lO.SMO  QIO  or  including  /RW  or  /REW  switches  to  command 
requests  (such  as  DNP) . 


l..y  ^   ■,' 
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CHAPTER  9 
CASSETTE  DRIVER 


9.1   INTRODUCTION 

RSX-llM  supports  the  TAll  magnetic  tape  cassette  (a  TAll  controller 
with  a  TU60  dual  transport).  Programming  for  cassette  Is  quite 
similar  to  programming  for  magtape  (see  Chapter  8).  The  TAll  system 
Is  a  dual-drive,  reel-to-reel  unit  designed  to  replace  paper  tape. 
Its  two  drives  run  nonsimultaneously,  using  DIGITAL  Proprietary 
Philips-type  cassettes. 

The  maximum  capacity  of  a  cassette.,  in  bytes,  is  92,000  (minus  300  per 
file  gap  and  46  per  interrecord  gap) .  It  can  transfer  data  at  speeds 
o''  up  to  562  bytes  per  second.  Recording  density  ranges  from  350  to 
700  bits  ber  inch,  depending  on  tape  postion. 


9.2   GET  LUN  INFORMATION  MACRO 

Word  2  of  the  buffer  filled  by  the  Get  LUN  Information  system 
directive  (the  first  characteristics  word)  contains  the  following 
information  for  cassettes.  A  bit  setting  of  1  indicates  that  the 
described  characteristic  is  true  for  cassettes. 

Meaning 

Record-oriented  device 

Carriage-control  device 

Terminal  device 

File  structured  device 

Single-directory  device 

Sequential  device 

Mass  storage  device 

User-mode  diagnostics  supported 

Device  supports  22-bit  direct  addres.  ing 


Bit 

Setting 

0 

1 

i 

9 

2 

0 

■  5^:, , 

9 

-*:,' 

,©■'■ 

t 

-   I 

6 

X 

7.'.     ' 

e 

• 

0 
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Naanlng 

Unit  software  wr ite-lock«d 

Input  spooled  device 

Output  spooled  device 

Pseudo  device 

Device  mountable  as  a  communications  channel 

Device  mountable  as  a  FILES-11  volume 

Device  mountable 

Words  3  and  4  of  the  buffer   are   undefined;    word   5   indicates   the 
default  buffer  size,  for  cassettes  128  bytes. 


•it 

Betting 

0 

0 

0 

0 

0 

0 

0 

9.3   QIO  MACRO 

Thlf.  section  summarizes  standard  and  device-specific  QIO  functions  for 
the  cassette  driver. 


9.3.1  Standard  QIO  Functions 

Table  9-1  lists  the  standard  functions  of  the  QIO  macro  that  are  valid 
for  cassette. 


Table  9-1 
Standard  QIO  Functions  for  Cassette 


'■  .■;  ■■•■;■■ 

Format 

Function 

QIO$C 

10. ATT,... 

Attach  .device 

QIO$C 

lO.DET,... 

Detach  device 

QIO$C 

lO.KIL,... 

Cancel  I/O  requests 

QIO$C 

lO.RLB, . . . ,<stadd,size> 

READ  logical  block 
(read  tape  into  buffer) 

QIOSC 

lO.RVB, . . . ,<stadd,size> 

READ  virtual  block 

(read  tape  into  buffer) 

QIO$C 

lO.WLB, . . . ,<stadd,size> 

WRITE  logical  block 
(write  buffer  contents  to 

■'',■  '- 

tape) 

QIO$C 

lO.WVB, . . . ,<stadd,size> 

/VK.'TE  virtual  block 

-,.-,, 

(wr^te  buffer  contents  to 
tape) 
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stadd 


The  starting  address  of  the  data   buffer   (may  be  on   a   byte 
boundary) . 


size 


The  data  buffer  size  in  b/tes  (must  be  greater  than  0) . 


lO.KIL  does  not  affect  in-progre.is  requests. 


9.3.2  Device-Specific  QIO  Functions 

Table  9-2  lists  the  device-specific  functions  of  the  QIO  macro  that 
are  valid  for  cassette.  The  section  on  programming  hints  below 
provides  more  detailed  information  about  certain  functions. 


9.4   STATUS  RETURNS 

The  error  and  status  conditions  listed  in  Table  9-3  are   returned   by 
the  cassette  driver  described  in  this  chapter. 


Table  9-2 
Device-Specific  QIO  Functions  for  Cassette 


Format 

Function 

QIO$C 

10. EOF,.., 

Write  end-of-file 

gap 

QIO$C 

lO.RWD,. .. 

Rewind  unit 

QIO$C 

lO.SPB,... 

,<nbs> 

SPACE  blocks 

QIOSC 

lO.SPF,. .. 

,<nes> 

SPACE  files 

nbs 


nes 


The  number  of  blocks  to  space  past  (positive  if  forward,  negative 
if  reverse)  . 


The  number  of  EOF  gaps   to   space   past   (positive   if   forward, 
negative  if  reverse). 
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Table  9-3 
Cassett";  Status  Returns 


Code 

Reason 

IS. sue 

Successful  completion 

The  operation  specified  in  the  QIO  directive  was 
completed  successfully.  The  second  word  of  the  I/O 
status  block  can  be  examined  to  determine  the 
number  of  bytes  processed  if  the  opera*:  ion  involved 
reading  or  writing,  or.  the  number  of  blocks  or 
files  spaced  if  the  operation  involved  spacing 
blocks  or  files. 

IS.PND 

I/O  request  pending 

The  operation  specified  in  the  QIO  directive  has 
not  yet  been  executed.  The  I/O  status  block  is 
filled  with  Os. 

IE. ABO 

Operation  aborted 

The  specified  I/O  operation  was  canceled  by  lO.KIL 
while  still  in  the  I/O  queue. 

lE.DAA 

Device  already  attached 

The  physical  device  unit  specified  in  an  10. ATT 
function  was  alrr>ady  attached  by  the  issuing  task. 
This  code  indicates  that  the  issuing  task  has 
already  attached  the  desired  physical  device  unit, 
not  that  the  unit  was  attached  by  another  task. 

lE.DAO 

Data  overrun 

The  driver  was  not  able  to  sustain  the  data  rate 
required  by  the  TAll  controller. 

lE.DNA 

Device  not  attached 

The  physical  device  unit  specified  by  an  lO.DET 
function  was  not  attached  by  the  issuing  task. 
This  code  has  no  bearing  on  the  attachment  status 
of  other  tasks. 

lE.DNR 

Device  not  ready 

The  physical  device  unit  specified  in  the  QIO 
directive  was  not  ready  to  perform  the  desired  I/O 
operation.  This  code  is  returned  to  indicate  one 
of  the  following  conditions: 

•   The  cassette  has  not  been  physically  inserted. 

•   The  unit  is  off  line. 

•   A  time-out  occurred  on  the  physical  device   unit 
(that  is,  an  interrupt  was  lost). 

(continued  on  next  page) 
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Code 


IE. EOF 


IE. EOT 


IE. IPC 


lE.OFL 


lE.SPC 


lE.VER 


lE.WLK 


Taole  9-3   (Cont.) 
Cassette  Status  Returns 


Reason 


End-of-file  encountered 

An  end-of-file  gap  was  recognized  on  the  cassette 
tape.  This  code  is  returned  if  an  EOF  gap  is 
encountered  during  a  read,  or  if  the  cassette  is 
physically  removed  during  an  I/O  operation. 


End-of-tape  encountered 


While 
end-o 

readi 
f-tape 

writing   beyo 
This     condit 
it    would    be 

tape.         If 
cassette   hea 
the      writing 
thf»t    the    use 

cassette. 

ng  or  writing,  clear 
(EOT)  was  encountered.  Un 
nd  EOT  is  not  permitted  o 
ion  is  always  sensed  on  a 
sensed  on  a  read  of  the  sa 
IE. EOT  is  returned  during 
d  has  encountered  EOT  befo 
of  the  last  block.  It  i 
r  entirely  rewrite  the  bio 


trailer  at 
like  magtape, 
n  cassettes. 

write  before 
me  section  of 

a  write,  the 
re  finishing 
s  recommended 
ck  on  another 


Illegal  function 

A  function  code  was  specified  in  an  I/O  request 
that  is  illegal  for  cassette. 

Device  off  line 

The  physical  device  unit  associated  with  the  LUN 
specified  in  the  QIO  directive  was  not  on  line. 
When  the  system  was  booted,  a  device  check 
indicated  that  this  physical  device  unit  was  not  in 
the  configuration. 

Illegal  address  space 

The  buffer  specified  for  a  read  or  write  request 
was  partially  or  totally  outside  the  address  space 
of  the  issuing  task.  Alternatively,  a  byte  count 
of  0  was  specified  on  a  transfer. 

Nonrecoverable  error 


This  code  is  ret 
occurs  (see  Sec 
check  (CRC) ,  a  2 
each  block,  is  a 
read  operations 
correctly.  Thi 
not  specify  exac 
the  record  on 
returned,  the  us 
backward  one  bio 


urned   when  a   block  check  error 

tion  9.6.5).   The  cyclic  redundancy 

b\'f-f>  value  located  at  the  end   of 

c.(   ksum  that  is  tested  during  all 

to   ensure   that   data   is    read 

s  is  returned  if  a  read  request  did 

Lly  the  number  of  bytes  of  data   in 

tape.   If  a  nonrecoverable  error  is 

er  may  attempt  recovery  by  spacing 

ck  and  retrying  the  read  operation. 


Write-locked  device 

The  task  attempted  to  write  on  a  cassette  unit  that 
was  physically  write-locked.  This  code  may  be 
returned  after  an  lO.WLB,  lO.WVB,  or  10. EOF 
function. 
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9.4.1   Cassette  Recovery  Procedures 

If  an  error  occurs  during  a  read  or  write  operation,  the  operation 
should  be  retried  several  times.  The  recommended  maximum  number  of 
retries  is  nine  for  a  read  and  three  for  a  write  because  each  retry 
involves  backspacing,  which  does  not  always  position  the  tape  in  the 
same  place.  More  than  three  retries  of  a  write  operation  may  destroy 
previously  written  data.  For  example,  to  retry  a  write,  it  is  best  to 
space  two  blocks  in  reverse,  then  space  one  block  forward.  This 
insures  the  tape  is  in  the  proper  position  to  rewrite  the  block  that 
encountered  the  error. 

After  read  and  write  functions,  the  second  I/O  status  word  contains 
the  number  of  bytes  actually  processed  by  the  function.  After  spacing 
functions,  it  contains  the  number  of  blocks  or  files  actually  spaced. 


9.5   STRUCTURE  OF  CASSETTE  TAPE 

Figure  9-1  illustrates  a  general  structure  for  cassette  tape.  A 
different  structure  can  be  employed  if  the  user  wishes. 

Here  the  tape  consists  of  blocks  of  data  interspersed  with  sections  of 
clear  tape  that  serve  as  leader,  trailer,  interrecord  gaps  (IRGs),  and 
end-of-file  gaps. 

The  logical  end-of-tape  in  this  case  consists  of  a  sentinel  label 
record,  rather  than  the  conventional  group  of  end-of-file  gaps.  Each 
file  must  contain  at  least  one  block.  The  size  of  each  block  depends 
upon  the  number  of  bytes  the  user  specifies  when  writing  the  block. 


IRGS 


BOT 


CL 


L?G 


LR    IREC 


REC 


REC 


EOF 


LR  BREC 


REC  I  EOF 


SLR 


EOT 


CT 


FILE  1 


FILE  2 


LEOT 


150  FEET 


ZK-006-81 


Abbreviation 

CL 

BOT 

LPG 

LR 
REC 


Figure  9-1   Structure  of  Cassette  Tape 

Meaning 

Clear  leader 

Physical  beginning-of-tape 

Load  point  g?;->   (blank   tape  written   by  driver 
before  the  fir.   retrievable  record) 

File  label  record 

Fixed-length  record  (data) 
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Abbreviation  Meaning 

EOF  End-of-file  gap 

IRG  Interrecord  gap 

SLR  Sentinel  label  record 

LEOT  Logical  end-of-tape 

EOT  Physical  end-of-tape 

CT  Clear  trailer 

9.6   PROGRAMMING  HINTS 

This  section  contains  information  on  important  programming 
considerations  relevant  to  users  of  the  cassette  driver  described  in 
this  chapter. 


9.6.1   Importance  of  Rewinding 

The  first  cassette  operation  performed  on  a  tape  must  always  be  a 
rewind  to  ensure  that  thp  tape  is  positioned  to  a  known  place.  When 
it  is  positioned  in  clear  tape,  there  is  no  way  to  determine  whether 
it  is  in  leader  at  the  beginning-of-tape  (BOT)  or  in  trailer  at  the 
end-of-tape  (EOT) . 


9.6.2  End-of-File  and  lO.SPF 

The  hardware  senses  end-of-file  (EOF)  as  a  time-out.  When  lO.SPF  is 
issued  in  the  forward  direction  (nes  is  positive),  the  tape  is 
positioned  f-'-^-thirds  of  the  way  from  the  beginning  of  the  final  file 
gap.  In  effect,  this  is  all  the  way  through  the  file  gap.  When 
lO.SPF  is  issued  in  the  reverse  direction  (nes  is  negative),  the  tape 
is  positioned  one-third  of  the  way  from  the  beginning  of  the  final 
file  gap  (that  is,  two-thirds  of  the  way  from  the  beginning  of  the 
last  file  spaced).  Therefore,  to  correctly  position  the  tape  for  a 
read  or  write  ^fter  issuing  lO.SPF  in  reverse,  the  user  should  issue 
lO.SPB  forward  for  one  block,  followed  by  lO.SPB  in  reverse  for  one 
block. 


9.6.3  The  Space  Functions,  lO.SPB  and  lO.SPF 

lO.SPB  always  stops  in  an  IRG  gap,  lO.SPF  in  an  EOF  gap.  Neither 
space  function  actually  takes  effect  until  data  is  encountered.  For 
example,  suppose  the  tape  is  positioned  in  clear  leader  at  BOT  and  the 
user  requests  that  one  block  be  spaced  forward.  The  drive  passes  over 
the  remaining  leader  until  it  reaches  data,  passes  one  olock,  and 
stops  in  the  IRG.  Similarly,  if  the  same  command  is  issued  when  the 
tape  is  at  BOT  on  a  blank  tape  or  a  tape  containing  only  EOF  gaps,  the 
function  does  not  terminate  until  EOT. 
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9.6.4   Verifying  of  Write  Operations 

Certain  errors,  such  as  cyclic  redundancy  check,  are  detected  on  read 
but  not  write  operations.  Therefore,  to  ensure  reliability  of 
recording,  it  is  recommended  that  the  user  perform  a  read  in  order  to 
verify  every  write  operation. 


9.6.5  Block  Length 

The  user  must  specify  the  exact  number  of  bytes  per  block  wh'^n 
requesting  read  or  write  operations.  An  attempt  to  read  a  block  with 
an  incorrect  byte  count  causes  an  unrecoverable  error  (see  Section 
9.4)  to  occur. 


9.6.6   Logical  End-of-Tape 

The  conventional  method  of  signaling  logical  end-of-tape  by  multiple 
EOF  gaps  is  inadequate  for  cassettes,  because  multiple  EOF  gaps  are 
not  distinguishable  from  each  other.  For  example,  two  sequential  EOF 
gaps  would  be  read  as  three  instead  of  two.  Also  spacing  functions, 
since  they  are  triggered  by  encountering  data,  can  not  recognize 
multiple  EOF  gaps.  Consequently,  the  use  of  a  sentinej.  or  key  record 
to  signal  logical  end-of-tape  is  recommended. 
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10.1   INTRODOCTION 

The  RSX-llM  line  printer  driver  supports  the  line  printers  summarized 
in  Table  10-1.  Subsequent  sections  of  this  chapter  describe  these 
printers  in  greater  detail. 

Table  10-1 
Standard  Line  Printer  Devices 


Controller 

Printer 

Column  Width 

Character  Set 

Lines  per  Minute 

LPll-C 

LP14-C 

132 

64 

890 

LPll-D 

LP14-D 

132 

96 

650 

LPll-F 

LPOl-c' 

80 

64 

170-1110 

LPll-H 

LPOl-H 

80 

96 

170-1110 

LPll-J 

LP02-J 

132 

64 

170-1110 

LPll-K 

LP02-K 

132 

96 

i70-lllD 

LP;.1-R 

LP04-R 

132 

64 

1110 

LPII-S 

LP04-S 

132 

96 

.110 

LPll-V 

LP05-V 

132 

64 

'CO 

LPll-W 

LP05-W 

132 

96 

)0 

LPll-Y 

LP06-Y 

132 

64 

600 

LPll-Z 

LP06-Z 

132 

96 

460 

LPll-GA 

LP07 

132 

96 

1200 

LPll-EA 

LP26 

132 

64 

600 

LPil-EB 

LP26 

132 

64/96 

600/420 

LPll-UA 

LP27 

132 

64/96 

1200/800 

LSll 

LSll 

132 

62 

60-200 

LVll 

LVOl 

132 

96 

500 

LA180 

LA180 

132 

96 

150 

LNOl 

LNOl 

Variable 

* 

600 

*   Software 


selectable  fonts  not  s 

10- 


upported  by  RSX. 
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10.1.1   LPll  Line  Printer 


The  LPil  is  a  high-speed  line  p 
models.  The  LPll  model  line  co 
line  printers.  The  drum  printers 
hammer  per  column  and  a  revol 
lowercase  characters.  The  LPll-R 
that  operate  at  a  standard  speed 
LPll  drum  models  have  20-characte 
therefore  able  to  print  at  full  s 
than  20  characters.  Lines  that  e 
slov.  3r  rate.  Forms  with  up 
copies.  The  band  line  printers  a 
steel  belt  with  raised  metal  cha 
and  LP27  offer  speeds  from  420  to 


rinter  available  in  a  variety  of 
nsists  of  band  line  printers  and  drum 

are  impact  printers,  that  use  one 
ving  drum  with  uppercase  and  optional 

and  LPll-S  are  fully  buffered  models 

of  1110  lines  per  minute.  The  other 
r  print  buffers.  These  printers  are 
peed  if  the  printed  line  is  no  longer 
xceed  this  maximum  are  printed  at  a 
to  six  parts  may  be  used  for  multiple 
re  impact  printers  that  have  a  flat 
racters  on  the  face.   The  LP07,  LP26, 

1200  lines  pet  minute. 


10.1.2   LSll  Line  Printer 

The  LSll  IS  a  medium-speed  line  printer.  It  has  a  20-character  print 
buffer,  and  lines  of  20  characters  or  less  are  printed  at  a  rate  of 
200  lines  per  minute.  Longer  lines  are  printed  at  a  slower  rate. 
RSX-ilM  does  not  support  the  LSll  expanded  character  set  feature. 


10.1.3   LVll  Line  Printer 

The  LVll  is  a  f ul iy-buf f ered ,  electrostatic  printer-plotter  that 
operates  at  a  standard  rate  of  500  lines  per  minute.  RSX-llM  supports 
only  the  LVll  print  capability,  not  the  plotter  mode. 


10.1.4   LA180  DECprinter 

The  LA180  is   a   180-character/sec ,   dot-matrix   impact   printer 
accepts  multipart  forms  and  pages  of  various  lengths  and  widths. 


It 


10.1.5   LNOl  Laser  Printer 

The  LNOl  is  a  non-impact  page  printer  that  uses  laser  imaging  combined 
with  xerographic  printing.  This  technology  provides  letter  quality 
printing  at  line  printer  speeds  with  no  noise.  Printing  is  done  on 
standard  8  1/2  inch  by  11  inch  paper  at  12  pages  per  minute,  which 
equates  to  600  lines  per  minute.  Contributing  to  the  high  print 
quality  is  a  printer  resolution  of  300  by  300  dots  per  inch.  The  LNOl 
offers  the  speed  of  a  line  printer  with  the  advantages  of  a 
phototypeset  device. 


10.2   GET  LON  INFORMATION  MftCRO 

Word  2  of  the  buffer  filled  by  the  Get  LUN  Information  system 
directive  (the  first  characteristics  word)  contains  the  following 
information  for  line  printers,  A  bit  setting  of  1  indicates  that  the 
described  characteristic  is  true  tcr  line  printers. 
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Bit 

Setting 

0 

1 

1 

1 

2 

0 

3 

0 

4 

0 

5 

0 

6 

0 

7 

0 

8 

0 

9 

0 

10 

0 

11 

0 

12 

0 

13 

0 

14 

0 

15 

0 

Meaning 

Record-oriented  device 

Carriage-control  device 

Terminal  device 

File  structured  device 

Single-directory  device 

Sequential  device 

Mass  storage  device 

User-mode  diagnostics  supported 

Device  supports  22-bit  direct  addressing 

Unit  software  write-locked 

Input  spooled  device 

Output  spooled  device 

Pseudo  device 

Device  mountable  as  a  communications  channel 

Device  mountable  as  a  FILES-11  volume 

Device  mountable 


Words  3  and  4  of  the  buffer  are  undefined;  word  5  indicates  the 
default  size  for  the  device,  for  line  printers  the  width  of  the 
printer  carriage  (that  is,  80  or  132). 
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10.3   QIO  MACRO 

Table  10-2  lists  the  standard  functions  of   the  QIO  macro   that  ace 
valid  for  line  printers. 


Table  10-2 
Standard  QIO  Functions  for  Line  Printers 


Format 

Function 

QIO$C 

10. ATT,... 

Attach  device 

QIO$C 

lO.DET, . . . 

Detach  device 

QIO$C 

lO.KIL,... 

Cancel  I/O  requests 

QIO$C 

lO.WLB, . . . ,<stadd ,size,vfc> 

WRITE  logical  block 
(print  buffer  contents) 

QIO$C 

lO.WVB, . . . ,<stadd,size,vfc> 

WRITE  virtual  block 
(print  buffer  contents) 

stadd 


The  starting  address  of   the  data   buffer   (may  be  on  a  byte 
boundary) . 


# 


size 


The  data  buffer  size  in  bytes  (must  be  greater  than  0) 


vfc 


A  vertical  format  control  character  from  Table  10-4, 
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lO.KIL  does  not  cancel  an  in-progress  request  unless  t  .e  line  printer 
is  in  an  off-line  condition  because  of  a  power  failure  or  a  paper  jam, 
or  because  it  is  out  of  paper. 

The  line  printer  driver  supports  no  device-specific  functions. 


10.4   STATUS  RETURNS 

Table  10-3  lists  the  error  and  status  conditions  that  are  returned   by 
the  line  printer  driver  described  in  this  chapter. 


Table  10-3 
Line  Printer  Status  Returns 


Code 

Reason 

IS. sue 

Successful  completion 

The  operation  specified  in  the  QIO  directive  wa ? 
completed   successfully.    The   second  word  of  the 
I/O  status  block  can  be  examined  to  determine   the 
number    of   bytes   processed,   if   the   operation 
involved  writing. 

IS.PND 

I/O  request  pending 

The  operation  specified  in  the  QIO  directive   has 
not   yet   been   executed.   The  I/O  status  block  is 
filled  with  Os. 

IE. ABO 

Operation  aborted 

The  specified  I/O  operation  was  canceled  while   in 
progress  or  while  in  the  I/O  queue. 

lE.OAA 

Device  already  attached 

The  physical  device  unit  specified   in   an   10. ATT 
function  was  already  attached  by  the  issuing  task. 
This  code  indicates   that   the   issuing   task   has 
already  attached  the  desired  physical  device  unit, 
not  that  the  unit  was  attached  by  another  task. 

lE.DNA 

Device  not  attached 

The   physical   device   unit   specified   an   lO.Dlvr 
function   was   not   attached   by  the  issuing  task. 
This  code  has  no  bearing  on  the  attachment   status 
of  other  tasks. 

IE. IPC 

Illegal  function 

A  function  code  was  specified  in   an   I/O  request 
that  is  illegal  for  line  printers. 

(continued  on  next  page) 
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Table  10-3   (Cont.) 
Line  Printer  Status  Returns 


Code 

Reason 

lE.OFL 
lE.SPC 

Device  off  line 

The  physical  device  unit  associated  with   the   LUN 
specified   in   the   QIO  directive  was  not  on  line. 
When   the   system  was  booted,   a  device   check 
indicated   that   this  physical  device  unit  was  not 
in  the  configuration. 

Illegal  address  space 

The  buffer   specified   for   a   write   request   was 
partially  or  totally  outside  the  address  space  of 
the  issuing  task.   Alternatively,  a  byte  count   of 
0  was  specified. 

10.4.1   Ready  Recovery 

If  any  of  the  following  conditions  occur: 

•  Paper  jam 

•  Printer  out  of  paper 

•  Printer  turned  off  line 

•  Power  failure 

the  driver  determines  that  the  line   printer   is  off  line,   and   the 
following  message  is  output  on  the  operator's  console: 

***LPn:  —  NOT  READY 


The  unit  number  of  the  line  printer  cnat  is  not  ready. 


The  driver  retries  the  function  that  encountered  the  error  condition 
from  the  beginning,  once  every  second.  It  displays  the  message  every 
m  seconds  (m  is  defined  at  SYSGEN  to  be  a  value  less  than  256.  The 
default  is  15)  until  the  line  printer  is  readiec.  If  a  power  *^ailure 
occurs  while  printing  a  line,  the  entire  line  is  reprinted  from  the 
beginning  when  power  is  restored. 


10.5   VERTICAL  FORMAT  CONTROL 

Table  10-4  summarizes  the  meaning  of  all  characters  used  for  vertical 
format  control  on  the  line  printer.  Any  one  of  these  characters  can 
be  specified  as  the  vfc  parameter  in  an  lO.WLB  or  lO.WVB  function. 
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Table  10-4 
Vertical  Format  Control  Characters 


Octal 
Value 


040 


060 


061 


053 


044 


000 


Chara'-  ter 


Blank 


Zero 


One 


Plus 


Do  1 1  a  r 
sign 

Null 


Meaning 


SINGLE  SPACE:  Output  a  line  feed,  print  the 
contents  of  the  buffer,  and  output  a  carriage 
return.  I'ormally,  printing  immediately 
follows  the  previously  printed  line. 

DOUBLE  SPACE:  Output  two  line  feeds,  print 
the  contents  of  the  buffer,  and  output  a 
carriage  return.  Normally,  the  buffer 
contents  are  printed  two  lines  below  the 
previously  printed  line. 

PAGE  EJECT:  Output  a  form  feed,  print  tne 
contents  of  the  buffer,  and  output  a  carriage 
return.  Normally,  the  contents  of  the  buffer 
are  printed  on  the  first  line  of  the  next 
page. 

OVERPRINT:  Print  the  contents  of  the  buffer 
and  perform  a  carriage  return,  normally 
overprinting  the  previous  line. 

PROMPTING  OUTPUT:  Output  a  line  feed  and 
then  print  the  contents  of  the  buffer. 

INTERNAL  VERTICAL  FORMAT:  The  buffer 
contents  are  printed  without  addition  of 
vertical  format  control  characters.  In  this 
mode,  more  than  one  line  of  guaranteed 
contiguous  output  can  be  printed  per  I/O 
request. 


All  other  vertical  format  control  characters  are  interpreted  as  blanks 
(040(8)). 


10.6   PROGRAMMING  HINTS 

This  section  contains  information  on  important  programming 
considerations  relevant  to  users  of  the  line  printer  driver  described 
in  this  chapter. 


10.6.1   RUBOUT  Character 

The  lirie  printer  driver  discards  the  ASCII  character  code  177  during 
output,  because  a  RUBOUT  on  the  LSll  printer  causes  a  RUBOUT  o''  the 
hardware  print  buffer. 
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10.6.2   Print  Line  Truncation 


If  the  number  of  characters  to  be  printed  exceeds  the  width  of  the 
print  carriage,  the  driver  discards  excess  characters  until  it 
receives  one  that  instructs  it  to  empty  the  buffer  and  return  to 
horizontal  position  1.  The  user  can  determine  that  truncation  will 
occur  by  issuing  a  Get  LUN  Information  system  directive  and  examining 
word  5  of  the  information  buffer.  This  word  contains  the  width  of  the 
print  carriage  in  bytes. 


10.6.3  Aborting  a  Task 

If  a  task  is  aborted  while  waiting  for  the  lino  printer  to  be  readied, 
the  line  printer  driver  recognizes  this  fact  within  1  second. 
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CHAPTER  11 
CARD  READER  DRIVER 


11.1   INTRODUCTION 

The  RSX-llM  card  reader  driver  supports  the  CRll  card  reader.  This 
reader  is  a  virtually  jam-proof  device  that  reads  EIA  standard 
80-column  punched  cards  at  the  rate  of  300  per  minute.  The  hopper  can 
hold  600  cards.  This  device  uses  a  vacuum  picker  that  provides 
extreme  tolerance  to  damaged  cards  and  makes  card  wear  insignificant. 
Cards  are  riffled  in  the  hopper  to  prevent  sticking.  The  reader  uses 
a  strong  vacuum  to  deliver  the  bottom  card.  Because  it  has  a  very 
short  card  track,  only  one  card  is  in  motion  at  a  time. 


11.2   GET  LUN  INFORMATION  MACRO 

Word  2  of  the  buffer  filled  by  the  Get  LUN  Information  system 
directive  (the  first  characteristics  word)  contains  the  following 
information  for  card  readers.  A  bit  setting  of  1  indicates  that  the 
described  characteristic  is  true  for  card  readers. 

Meaning 

Record-oriented  device 

Carriage-control  device 

Terminal  device 

File  structured  device 

Single-directory  device 

Sequential  device 

Mass  storage  device 

User-mode  diagnostics  supported 

Device  supports  22-bit  direct  addressing 

Unit  software  write-locked 


Bit 

Setting 

0 

1 

1 

0 

2 

0 

3 

0 

4 

0 

5 

0 

6 

0 

7 

0 

8 

0 

9 

0 

• 
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10 
11 

12 
13 

14 

15 


Setting 
0 
0 
0 
0 

0 
0 
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Meaning 

Input  spooled  device 

Output  spooled  device 

Pseudo  device 

Device  mountable  as  a  communications 
channel 

Device  mountable  as  a  FILES-11  volume 

Device  mountable 


Words  3  and  4  of  the  buffer   are   undefined;    word   5   indicates   the 
default  buffer  size,  which  is  80  bytes  for  the  card  reader. 


11.3   QIO   MACRO 

This  section  summarizes  standard  and  device-specific  QIO  functions  for 
the  card  reader  driver. 


11.3.1  Standard  QIO  Functions 

Table  11-1  lists  the  standard  functions  of   the   QIO  macro   that   are 
valid  for  the  card  reader. 


Table  11-1 
Standard  QIO  Functions  for  the  Card  Reader 


Format 

Function 

QIOSC 

10. ATT, .. . 

Attach  device 

QIOSC 

lO.DET,... 

Detach  device 

QIOSC 

lO.KIL,. .. 

Cancel  I/O  requests 

QIOSC 

10. RLE, . . . ,<stadd ,size> 

READ  logical  block 
(alphanumeric) 

QIOSC 

lO.RVB, . . . ,<stadd,size> 

READ  virtual  block 
(alphanumeric) 

stadd 


The  starting  address  of   the   data  buffer   (may  be  on   a   byte 
boundary) . 


size 


The  data  buffer  size  in  bytes  (must  be  greater  than  0). 


lO.KIL  does  not  cancel  an  in-progress  request  unless  the  card  reader 
is  in  an  off-line  condition  because  of  a  pick,  read,  stack,  or  hopper 
check,  because  of  power  failure,  or  because  the  RESET  button  has  not 
been  depressed. 
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11.3.2  Device-Specific  QIO  Functions 

The  device-specific  functions  of  the  QIO  macro  that  are  valid  for   the 
card  reader  are  shown  in  Table  11-2. 


Table  11-2 
Device-Specific  QIO  Function  for  the  Card  Reader 


Format 

Function 

OIOSC  lO.ATA,. . .,<AST  addr> 
OIO$C  lO.RDB, . . . ,<stadd,size> 

Attach  for  unsolicited  card  AST 
Read  locjical  block  (binary) 

stadd 


size 


The  starting  address  of   the   data   buffer   (may   be   on   a   byte 
boundary) . 


The  data  buffer  size  in  bytes  (must  be  greater  than  0) 


11.4   STATUS  RETURNS 

A  wide  variety  of  error  conditions  and  recovery  procedures  relate  to 
the  use  of  the  card  reader.  This  section  describes  the  three  major 
ways  in  which  the  system  reports  error  conditions. 

1.  Lights  and  indicators  on  the  card  reader  panel  are  turned  on 
or  off  to  indicate  particular  operational  problems  such  as 
read,  pick,  stack,  or  hopper  checks.  Switches  are  available 
to  turn  the  reader  power  on  and  off  and  to  allow  the  user  to 
reset  after  correcting  an  error  condition. 

2.  A  message  is  output  on  the  operator's  console  if  operational 
checks  or  power  problems  occur. 

3.  An  I/O  completion  code  is  returned  in  the  low-order  byte  of 
the  first  word  of  the  I/O  status  block  specified  in  the  QIO 
macro  to  indicate  success  or  failure  on  completion  of  an  I/O 
function. 


The  following  subsections  describe  each  of  thase  returns  in  detail 


11.4.1  Card  Input  Errors  and  Recovery 

The  table  included  below  describes  all  external  lights  and  switches 
used  to  indicate  to  the  operator  that  a  hardware  problem  has  occurred 
and  must  be  corrected.   There  are  two  classes  of  hardware  errors: 


•  Those  requiring  the  operator  to  ready  the  reader  and  try  the 
operation  again 

•  Those  requiring  the  operator  to  remove  the  last  card  from  the 
output  stacker,  to  replace  it  in  the  input  hopper,  and  to  try 
the  operation  again 
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In  the  first  case,  the  card  reader  was  unable  to  read  the  current 
card.  In  the  second,  the  card  was  read  incorrectly  and  must  be 
physically  removed  from  the  output  stacker.  The  card  reader  driver 
automatically  restarts  a  read  operation  within  1  second  after  the 
cards  have  been  replarcd  in  the  input  hopper. 

Table  11-3  summarizes  the  functions  of  lights  and  indicators  on  the 
front  panel  of  the  card  reader.  It  discusses  common  operational 
errors  that  might  be  encountered  while  reading  cards  and  recovery 
procedures  associated  with  these  error  conditions. 


11.4.2  Ready  and  Card  Reader  Check  Recovery 

If  any  of  the  following  conditions  occur: 

•  Power  failure 

•  Reset  switch  not  pressed  (reader  off  line) 

•  Timing  error  (Two  columns  were  read   before   the   card   reader 
driver  input  the  first  column  from  the  card  reader.) 

the  driver  determines  that  the  card  reader  is  not  ready,  and  the 
following  message  is  output  on  the  operato''s  console: 

***  CRn:  —  NOT  READY 

When  a  timing  error  occurs,  the  operator  can  proceed  with  normal  card 
reader  operation  by: 

1.  Placing  the  card  reader  off  line  by  pressing  the  STOP  switch 

2.  Removing  the  last  card  read  and  inserting  it  where  it  will  be 
the  next  card  read 

3.  Placing  the  card  reader  on  line  by  pressing  the  RESET  switch 
If  any  of  the  following  conditions  occurs: 

•  Pick  error  (PICK  CHECK) 

•  Read  error  (READ  CHECK) 

•  Output  stacker  error  (STACK  CHECK) 

•  Input  hopper  out  of  cards  (HOPPER  CHECK) 

•  Output  stacker  full  (HOPPER  CHECK) 

the  driver  determines  that  a  card  reader  check  has  occurred,  and  the 
following  message  is  output  on  the  operator's  console: 

***  CRn:  —  READ  FAILURE.  CHECK  HARDWARE  STATUS 

where  n  is  the  unit  number  of  the  card  reader  that  is  not  ready.  The 
operator  should  correct  the  error  and  press  RESET:  The  driver 
attempts  the  function  from  the  beginning,  once  every  second.  It 
displays  the  message  once  every  m  seconds  (m  is  defined  at  SYSGEN  as  a 
value  less  than  256.  The  default  is  15)  until  the  card  reader  is 
readied.  In  all  cases  except  pick  error,  the  last  card  read  should  be 
reinserted  in  the  input  hopper,  as  described  in  Section  11.4.1. 


11-4 


CARD  READER  DRIVER 


Table  11-3 
Card  Reader  Switches  and 


Ind  icators 


Indicator 

Description 

Action 

Recovery 

POWER 

Pushbutton 

Controls  application 

Card  may  have  been 

Switch 

indicator 

of  all  power  to  the 

read  incorrectly; 

switch 

card  reader. 

restore  power  if 

(alternate 

possible  by  depress- 

action: 

When  indicator  is 

ing  the  POWER 

pressed  for 

off,  depressing  switch 

switch;  insert  the 

both  ON  and 

applies  power  to 

card  again  as  the 

OFk') 

reader  and  causes 

first  card  in  the 

associated  indica- 

input hopper,  and 

tor  to  light. 

press  the  RESET 
switch;  in  some 

When  indicator  is 

cases,  it  may  be 

lit,  depressing 

necessary  to 

switch  removes  all 

restart  the  program. 

power  from  reader  and 

causes  indicator  to 

go  out. 

READ 

White  light 

When  lit,  this  light 

Card  was  read  incor- 

CHECK 

indicates  that  the 

rectly;  duplicate  if 

Indicator 

card  just  read  may  be 

necessary,  insert 

torn  on  the  leading  or 

the  card  again  as 

trailing  edges,  or 

the  first  card  in  the 

that  the  card  may 

input  hopper,  and 

have  punches  in 

press  the  RESET 

column  positions  0 

switch. 

or  81. 

Because  READ  CHECK 

indicates  an  error 

condition,  whenever 

this  indicator  is 

lit,  it  causes  the 

card  reader  to  stop 

operation  and  extin-- 

guishes  the  RESET 

indicator. 

PICK 

White  light 

When  lit,  this  light 

Card  could  not  be 

CHECK 

indicates  that  the 

read;  press  the 

Indicator 

card  reader  failed  to 

RESET  switch  to  try 

move  a  card  into  the 

again  or  remove  the 

read  station  after 

cards  from  the  input 

it  received  a  READ 

hopper,  smooth  the 

COMMAND  from  the 

leading  edges,  re- 

controller. 

place,  and  then 
press  the  RESET 
switch. 

Stops  card  reader 

operation  and  extin- 

guishes RESET 

indicator . 

(continued  on  next  page) 
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Table  11-3   (Cent.) 
Card  Reader  Switches  and  Indicators 


Indicator 

Description 

Action 

Recovery 

STACK 

White  light 

When  lit,  this  light 

Card  may  have  been 

CHECK 

indicates  that  the 

read  incorrectly  and 

Indicator 

previous  card  was  not 

is  not  positioned 

properly  seated  in 

properly  in  the  out- 

the output  stacker 

put  stacker;  dupli- 

and therefore  may  be 

cate  the  card  if  it 

badly  mutilated. 

is  damaged;  insert 
the  card  again  as 

Stops  card  reader 

the  first  card  in 

operation  and  ex- 

the input  hopper  and 

tinguishes  RESET 

press  the  RESET 

indicator. 

switch. 

HOPPER 

White  light 

When  lit,  this  light 

Card  may  have  been 

CHECK 

indicates  that  either 

read  incorrectly; 

Indicator 

the  input  hopper  is 

empty  the  stacker  or 

empty  or  that  the  out- 

fill the  hopper;  in- 

put stacker  is  full. 

sert  the  card  agaii. 
as  the  fist  card  in 
the  input  hopper  and 
press  the  RESET 
switch. 

STOP 

Momentary 

When  depressed. 

Switch 

pushbutton/ 

immediately  lights 

indicator 

and  drops  the  READY 

switch 

line,  thereby  extin- 

(red light) 

guishing  the  RESET 
indicator.  Card 
reader  operation  then 
stops  as  soon  as  the 
card  currently  in  the 
read  station  has  been 
read . 

This  switch  has  no 
effect  on  the  system 
power;  it  only  stops 
the  current  operation. 

RESET 

Momentary 

When  depressed  and 

Switch 

pushbutton/ 

released,  clears  all 

indicator 

error  flip-flops  and 

switch 

initializes  card 

(green 

reader  logic.  Associ- 

light) 

ated  RESET  indicator 
lights  to  indicate 
that  the  READY  signal 
is  applied  to  the  con- 
trol ler. 

The  RESET  indicator 
goes  out  whenever  the 
STOP  switch  is  de- 
pressed or  whenever 
an  error  indicator 
lights  (READ  CHECK, 
PICK  CHECK,  STACK 
CHECK,  or  HOPPER 

CHECK) . 
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11.4.3   I/O  Status  Conditions 

The  error  and  status  conditions  listed  in  Table  11-4  are   returned   by 
the  card  reader  driver  described  in  this  chapter. 


Table  11-4 
Card  Reader  Status  Returns 


Code 

Reason 

IS. sue 

Successful  completion 

The  operation  specified  in  the  QIO  directive   was 
completed   successfully.    The   second  word  of  the 
I/O  status  block  can  be  examined  to  determine   the 
number   -'f  bytes  processed,   if   the  operation 
involved  reading. 

IS.PND 

I/O  request  pending 

The  operation  specified  in  the  QIO  directive   has 
not   yet   been   executed.   The  I/O  status  block  is 
filled  with  Os. 

IE. ABO 

Operation  aborted 

The  specified  I/O  operation  was  cancelled  while  in 
progress  or  while  still  in  the  I/O  queue. 

TE.DAA 

Device  already  attached 

The  physical  device  unit  specified   in   an   10. ATT 
function  was  already  attached  by  the  issuing  task. 

lE.DNA 

Device  not  attached 

The  physical  device  unit  specified   in   an   lO.DET 
function   was   not   attached   by  the  issuing  task. 
This  code  has  no  bearing  on  the  attachment   status 
of  other  tasks. 

IE. EOF 

End-of-file  encountered 

An  end-of-file  control  card  was  recognized. 

lE.IFC 

Illegal  function 

A  function  code  was  specified  in   an   I/O   request 
that  is  illegal  for  card  readers. 

IE. NOD 

Buffer  allocation  failure 

Dynamic  storage  space  has  been  depleted,  and  there 
was    insufficient    buffer    space   available   to 
allocate  a  card  buffer  (that  is,   cards   are   read 
into   a   driver  buffer,  translated,  and  then  moved 
to  the  user  buffer). 

(continued  on  next  page) 
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Table  11-4   (Cont.) 
Card  Reader  Status  Returns 


Code 

Reason 

lE.OFL 

Device  off  line 

The  physical  device  unit  associated  with  the   LUN 

specified   in   the   010  directive  was  not  on  line. 

When   the   system  was  booted,   a   device   check 

indicated   that   this  physical  device  unit  was  not 

in  the  configuration. 

lE.SPC 

Illegal  address  space 

The  buffer   specified   for   a   read   request   was 

pat  <ally  or  totally  outside  the  address  space  of 

the  issuing  task.   Alternatively,  a  byte  count  of 

0  was  specified. 

11.5   FUNCTIONAL  CAPABILITIES 

The  card  reader  driver  can  perform  the  following  functions: 

1.  Read  cards  in  DEC026  format  and  translate  to  ASCII 

2.  Read  cards  in  DEC029  format  and  translate  to  ASCII 

3.  Read  cards  in  b   ary  format 

If  the  OIO  macro  specifies  the  lO.RLB  or  lO.RVB  function,  the  driver 
interpets  all  data  as  alphanumeric  (026  or  029  format).  As  explained 
below,  control  characters  indicate  whether  026  or  029  is  desired.  If 
the  OIO  macro  specifies  10. ROB,  the  driver  interprets  all  data, 
including  026  and  029  control  characters,  as  binary. 

11.5.1  Control   Characters 

Table  11-5  lists  the  multipunched  cards  that  the  card  reader  driver 
recognizes  as  control  characters.  They  are  never  transferred  to  the 
user's  buffer  or  included  in  the  count  "f  transferred  bytes  in 
alphanumeric  mode.  In  binary  mode,  the  only  control  card  recognized 
is  binary  EOF. 

DCC026  is  the  default  translation  mode  when  the  system  is 
bootstrapped.  This  mode  remains  in  effect  until  explicitly  changed  by 
a  control  card  indicating  that  DEC029  cards  will  follow.  After 
encountering  a  DEC029  control  card,  the  driver  translates  all  cards  in 
DEC029  format  unless  another  DEC026  control  card  is  er.countered .  This 
card  overrides  the  029  mode  specification  )*nd  indicates  that 
subsequent  cards  are  to  be  translated  in  C26  format.  Control 
characters  are  addressed  to  the  card  reader  itself,  and  remain  in 
effect  even  when  the  reider  is  attached  and  subsequently  detached. 
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The  default  condition  can  easily  be  changed  from  DEC026  to  DEC029  by 
reading  a  029  control  card,  and  the:i  saving  the  system  with  the  MCR 
SAV  command. 


Table  11-5 
Card  Reader  Control  Characters 


Punches 

Columns 

Meaning 

12-11-0-1-6-7-8-9 

1 

End-of-file  (alphanumeric) 

12-11-0-1-6-7-8-9 

(All  8  punches  in 
the  first  8  columns) 

End-of-file  (binary) 

12-2-4-B 

1 

026-coded  cards  follow 

12-0-2-4-6-8 

1 

029-coded  cards  foHow 

11.6   CARD  READER  DATA  FORMA  S 

The  card  reader  reads  data  in  either  alphanumeric  or  binary  format, 


11.6.1  Alphanumeric  Format  (026  and  0211) 

Table  n    summarizes  the  translation  from  DEC026  or  DEC029  card  codes 
to  ASCii. 


11.6.2  Binary  Format 

In  RSX-llM  binary  format,  the  data  are  not  packed,  but  are  transferred 
exactly  as  read,  one  card  column  per  word.  Because  each  word  has  16 
bits  and  each  card  column  represents  only  12,  the  data  from  the  column 
are  stored  in  the  rightmost  12  bits  of  the  word.  The  word's  remaining 
four  bits  contain  Os. 


11.7   PROGRAMMING   HINTS 


This   section   contains    information  on    important   programming 

considerations   relevant   to  users  of  the  card  reader  driver  described 

in  this  chapter.   Section  11.4  contains  information  on  operational 

error-recovery  procedures   that  might  be  important  from  a  programming 
point  of  view. 


11.7.1   Input  Card  Limitation 

Only  one  card  can  be  read  with  a  single  010  macro  call.  A  request  to 
read  more  than  80  bytes  or  columns,  the  length  of  a  single  card,  does 
not  result  in  a  multiple  card  transfer.  Only  80  columns  are 
processed.  It  is  possible  to  read  fewer  than  80  columns  of  card  input 
with  a  010  read  function.  For  example,  the  user  can  specify  that  only 
the  first  10  columns  of  each  card  are  to  be  read. 
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11.7.2  Aborting  a  Task 

If  a  task  waiting  for  the  card  reader  to  be  readied   is  aborted,   the 
card  reader  driver  recognizes  this  fact  within  1  second. 


Table  11-6 
Translation  from  DEC026  or  DEC029  to  ASCII 


Non- 

Non- 

Parity 

Parity 

Character 

ASCII 

DEC029 

DEC026 

Character 

ASCII 

DEC029 

DEC026 

173 

12  0 

12  0 

t 

054 

0  8  3 

0  8  3 

175 

11  n 

11  0 

- 

055 

11 

11 

SPACE 

040 

none 

none 

• 

056 

12  8  3 

12  8  3 

! 

041 

12  8  7 

12  8  7 

/ 

057 

0  1 

0  1 

■ 

042 

8  7 

0  8  5 

0 

060 

0 

0 

• 

043 

8  3 

0  8  6 

1 

061 

1 

1 

$ 

044 

11  8  3 

11  8  3 

2 

062 

2 

2 

« 

045 

0  8  4 

0  8  7 

3 

063 

3 

3 

AND 

046 

12 

11  8  7 

4 

064 

4 

4 

1 

047 

8  5 

3  6 

5 

065 

5 

5 

( 

050 

12  8  5 

0  8  4 

6 

066 

6 

6 

) 

051 

11  8  5 

12  8  4 

7 

067 

7 

7 

* 

052 

11  8  4 

11  8  4 

8 

070 

8 

8 

+ 

053 

12  8  6 

12 

9 

071 

9 

9 

• 

072 

8  2 

11  8  2 

M 

115 

11  4 

11  4 

t 

073 

11  8  6 

0  8  2 

N 

116 

11  5 

11  5 

074 

12  8  4 

12  8  6 

0 

117 

11  6 

11  6 

= 

075 

8  6 

8  3 

P 

120 

11  7 

11  7 

> 

076 

0  8  6 

11  8  6 

0 

121 

11  8 

11  8 

7 

077 

0  8  7 

12  8  2 

R 

122 

11  9 

11  9 

P 

100 

8  4 

8  4 

S 

123 

0  2 

0  2 

A 

101 

12  1 

12  1 

T 

124 

0  3 

0  3 

B 

102 

12  2 

12  2 

U 

125 

0  4 

0  4 

C 

103 

12  3 

12  3 

V 

126 

0  5 

0  5 

D 

104 

12  4 

12  4 

w 

127 

0  6 

0  6 

E 

105 

12  5 

12  5 

X 

130 

0  7 

0  7 

F 

106 

12  6 

12  6 

Y 

131 

0  8 

0  8 

G 

107 

12  7 

12  7 

Z 

132 

0  9 

0  9 

H 

110 

12  8 

12  8 

[ 

133 

12  8  2 

11  8  5 

I 

111 

12  9 

12  9 

\ 

134 

0  8  2 

8  7 

J 

112 

11  1 

11  1 

] 

135 

11  8  2 

12  8  5 

K 

113 

11  2 

11  2 

-  or 

136 

11  8  7 

8  5 

L 

114 

11  3 

11  3 

_  °^ 

137 

0  8  5 

8  2 
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CHAPTER  12 
MESSAGE-ORIENTED  COMMUNICATION  DRIVERS 


12.1   INTRODUCTION 

RSX-llM  supports  a  variety  of  communication  line  interfaces: 
synchronous  and  asynchronous,  single-line  and  multiplexers, 
character-oriented  and  message-oriented.  These  are  used  for  terminal 
communications,  remote  job  entry,  multicomputer  interfaces,  and 
laboratory  and  industrial  control  communications.  Communications  line 
interfaces  can  be  roughly  divided  into  two  categories: 

•  Terminal  (character-oriented)  communications  devices 

•  Mul ticomouter  (message-oriented)  communications  devices 

Chapters  1,  2,  and  3  describe  the  character-oriented  asynchronous 
communications  line  interfaces  used  primarily  for  terminal 
communications.  The  Terminals  and  Communications  Handbook  contains 
more  detail  on  these  devices.  This  chapter  describes  in  some  detail 
the  RSX-llM  message-oriented  synchronous  and  asynchronous 
communication  line  interfaces.  These  are  used  most  frequently  in 
multicomputer  communications. 

Character-oriented  communications  devices  include  the  DHll,  DJll, 
DLll-A,  DLll-B/C/D,  and  DZ 1 1  interfaces.  These  are  asynchronous 
multiplexers  and  single-line  interfaces  used  almost  exclusively  for 
terminal  communications.  Transfers  on  all  of  these  interfaces  are 
performed  one  character  at  a  time.  None  of  the  interfaces  in  this 
category  has  a  driver  of  its  own  (that  is,  they  are  supported  by  the 
terminal  driver),  and  none  can  be  accessed  directly  as  RSX-llM 
devices. 

Message-oriented  communications  line  interfaces  are  used  primarily  to 
link  two  separate  but  complementary  computer  systems.  One  system  must 
serve  as  the  transmitting  device  and  the  other  as  the  receiving 
device.  Devices  in  this  category  include  the  synchronous  and 
asynchronous  single-line  interfaces  summarized  in  Table  12-1. 

The  message-oriented  communication  line  interfaces  are  used  primarily 
to  transfer  large  blocks  of  data. 

Whereas  the  character-oriented  interfaces  can  only  be  accessed 
indirectly  through  the  terminal  driver,  the  DAll-B,  DLll-E,  DMCll, 
DPll,  DQll,  DIJll,  and  DUPll  allow  I/O  requests  to  be  queued  directly 
for  them.  These  devices  have  drivers  of  their  own  and  can  be  accessed 
by  means  of  the  logical  device  names  listed  in  Table  1-1.  These  names 
can  be  used  in  assigning  LUNs  with  the  Assign  LUN  system  directive,  at 
task  build,  or  with  the  REASSIGN  MCR  command.  The  following 
subsections  briefly  discuss  the  message-oriented  interfaces  supported 
for  RSX-llM. 


12-1 


MBSSAGE-ORIENTED  COMMUNICATION  DRIVERS 


Table  12-1 
Message-Oriented  Communication  Interfaces 


Model 

Type 

Rate 
(KBaud) 

Duplex 

Half/Full 

Data  block 
(words) 

Synchronous 
Character 

DAll-B^ 

Paralle 

1 

500 

X 

32K 

No 

DL11-e2 

Serial, 

as'/r^hronous 

0.05-9,6 

X      X 

32K 

Programmable 

DMCll 

Seria? 

synchronous 

19.2-1000 

X      X 

8K 

No 

DPlll 

Ser' 

synchronous 

2-19.2 

X      X 

32K 

Programmable 

DOll^ 

Serial. 

synchronous 

2.4-1000 

X      X 

32K 

Programmable 

DUll^ 

Serial, 

synchronous 

0.05-9.6 

X      X 

32K 

Programmable 

DUPll 

Serial , 

synchronous 

0.05-9.6 

X      X 

32K 

Programmable 

1.  Support  Is  not  provided  on  RSX-llM-PLUS  systems. 

2.  DLll-E  support  is  provided  on  RSX-llM-PLUS   systems   using   the   full-duplex 
terminal  driver  only. 


12.1.1   DAll-B  Parallel  Interface 


The  DAll-B  provides  a  bit-parallel,  direct  memory  access  interface 
between  two  PDP-11  computer  systems.  Data  transfers  are  performed  a 
word  at  a  time  and  are  made  directly  between  the  memories  of  the  two 
systems.  The  maximum  transfer  rate  is  500,000  baud,  and  is  adjustable 
by  the  user  to  match  the  system  configuration  requirements.  Being  a 
parallel  device,  the  DAll-B  does  not  utilize  sync  characters.  The 
interface  is  half-duplex  and  transfers  data  in  blocks  of  up  to  32K 
words. 


The  DAll-B  requires  two  cooperating  computers  to  effect  a  data 
transfer.  In  order  to  control  the  physical  link  between  the 
computers,  the  device  driver  contains  its  own  simple  line  protocol. 
This  protocol  requires  one  system  to  issue  a  receive  QIO  and  the  other 
to  issue  a  transmit  QIC  before  any  data  is  actually  transferred. 


12.1.2  DLll-E  Asynchronous  Line  Interface 

The  DLll-E  is  an  asynchronous,  serial-bit,  single-line  interface.  It 
is  a  block-transfer  device  used  for  remote  terminal  and  multicomputer 
communications.  Baud  rates  are  selectable  becween  50  and  9600,  and 
full  data-set  control  is  supported.! 


1.  Software  support  for  data-set  control  consists  of  interlocking  RTS 
and  CTS  for  data  transmission,  and  the  setting  of  DTR  (data  terminal 
ready)  to  enable  auto-answer  modems  to  answer  incoming  calls.  DTR  is 
set  when  an  lO.INL  QIC  (initialize)  is  issued. 
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12.1.3  DMCll  Synchronous  Line  Interface 


The  IDMCll  provides  a  direct  memory  access  interface  between  two  PDP-11 
computer  systems  using  the  DDCMP  line  protocol,  thus  delivering  high 
throughput  and  reliability  while  simplifying  programming.  The  DMCll 
supports  Non-Processor  Request  (NPR)  data  transfers  of  up  to  8K  words 
at  rates  of  1,000,000  baud  for  local  operation  (over  coaxial  cable) 
and  19,200  baud  for  remote  operation  (using  modems).  Both  full-  and 
half-duplex  modes  are  supported.  The  DMCll  also  implements  remote 
load  detect,  allowing  it  to  reinitialize  a  halted  computer  system. 


12.1.4  DPll  Synchronous  Line  Interface 

The  DPll  provides  a  program  interrupt  interface  between  a  PDP-11  and  a 
serial  synchronous  line.  This  interface  facilitates  the  use  of  the 
PDP-11  in  remote  batch  processing,  remote  data  collection,  and  remote 
concentration  applications.  The  modem  control  feature  allows  the  DPll 
to  be  used  in  switched  or  dedicated  configurations. 


On  the  DPll,  baud  rates  are  selectable  between  2000  and  19,200.  The 
programmer  can  select  a  specific  sync  character  that  is  used  to 
synchronize  the  transmitting  and  receiving  systems. 


12.1.S  DQll  Synchronous  Line  Interface 

The  DQll  provides  a  direct  memory  access  interface  between  a  PDP-11 
and  a  serial  synchronous  line.  The  direct  memory  access 
characteristic  of  the  DQll  allows  the  device  to  operate  at  speeds 
higher  than  those  of  program  interrupt  devices,  and  with  a  lower 
interrupt  overhead.  Modem  control  of  the  DQll  allows  the  device  to  be 
used  in  switched  or  dedicated  configurations. 

The  DQll  handles  data  rates  from  2400  baud  to  1,000,000  baud.  The 
limiting  rate  is  determined  by  the  modem  and  data  set  interface  level 
converters. 


The  DQll  sync  character  is  programmable  in  the  same  manner  as  the  DPll 
and  the  DUll.  The  maximum  data  block  length  transmitted  is  fi5,536 
characters . 


12.1„6  DUll  Synchronous  Line  Interface 

The  DUll  synchronous  line  interface  is  a  single-line  communications 
device  that  provides  a  program-controlled  interface  between  the  PDP-11 
and  a  serial  synchronous  line.  The  PDP-11  can  be  interfaced  with  a 
high-speed  line  to  perform  remote  batch  processing,  remote  data 
collection,  and  remote  concentration  applications.  Modem  control  is  a 
standard  feature  of  the  DUll  and  allows  the  device  to  be  used  in 
switched  or  dedicated  configurations.  The  DUll  transmits  data  at  a 
maximum  rate  of  9600  baud;  this  rate  is  limited  by  modem  and  data  set 
interface  level  converters. 

The  DUll  can  be  programmed  to  accept  any  user-defined  sync  character. 
The  use  of  the  sync  character  is  the  same  for  the  DUll  and  the  DPll. 
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12.1.7  DUPll  Synchronous  Line  Interface 

The  DUPll  is  identical   to   the   DUll,   except   that   it   Incorporates 
hardware  to  perform  cyclic  redundancy  checking. 


12.2   GET  LUN  INFORMATION  MACRO 

Word  2  of  the  buffer  filled  by  the  Get  LUN  Information  system 
directive  (the  first  characteristics  word)  contains  the  following 
information  for  message-oriented  coirmunicat ion  interfaces.  A  bit 
setting  of  1  indicates  that  the  described  characteristic  is  true  for 
the  interfaces  described  in  this  chapter. 

Bit    Setting  Meaning 

Record-oriented  device 

Carriage-control  device 

Terminal  device 

File-structured  device 

Single-directory  device 

Sequential  device 

Mass  storage  device 

User-mode  diagnostics  supported 

Device  supports  22-bit  direct  addressing 

Unit  software  write-locked 

Input  spooled  device 

Output  spooled  device 

Pseudo  device 

Device  mountable  as  a  communications  channel 

Device  mountable  as  a  FILES-11  volume 

Device  mountable 

Words  3  and  4  are  undefined,  and  word  5  has  a  special  meaning  for  the 
DLll-E,  DQll,  DPll,  and  the  DUU  interfaces.  Byte  0  of  word  5 
contains  the  number  of  sync  characters  to  be  transmitted  before  a 
synching  message  (for  example,  after  line  turn-around  in  half-duplex 
operation),  and  byte  1  is  used  as  a  sync  counter. 


0 

0 

1 

0 

2 

0 

3 

0 

4 

0 

5 

0 

6 

0 

7 

0 

8 

0 

9 

0 

10 

0 

11 

0 

12 

0 

13 

1 

14 

0 

15 

1 
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12.3   QIO  MACRO 


This  section  summarizes  the  standard  and  device-specific  functions  of 
the  010  macro  that  are  valid  for  the  communication  interfaces 
described  in  this  chapter. 


12.3.1   Standard  QIO  Functions 

Table  12-2  lists  the  standard  functions  of   the   QIO  macro   that   are 
valid  for  tht  communication  devices. 


Table  12-2 
Standard  QIO   Functions  for  Communication  Interfaces 


Format 

Function 

OIOSC  lO.ATT,... 
OIOSC  lO.DET,... 
OIOSC  lO.KIL,... 
QIOSC  lO.RLB,. .. ,<stadd,size> 

0IO$C  lO.WLB, . . . ,<stadd,size> 

Attach  device^ 

Detach  device 

Cancel  I/O  requests 

READ  logical  block  (stripping 
sync) 

WRITE  logical  block  (preceded  by 
syncs) 

1.  Only  unmounted  channels  may  be  attached.  An  attempt  to  attach 
a  mounted  channel  will  result  in  an  lE.PRI  status  being  returned 
in  the  I/O  status  doubleword. 


stadd 


The  starting  address  of  the  data   buffer   (may   be   on   a   byte 
boundary) . 


size 


The  data  buffar  size  in  bytes  (must  be  greater  than  0) . 


12.3.2  Device-Specific  QIO  Functions 

The  specific  functions  of   the   QIO  macro   that   are   valid   for   the 
communication  line  interfaces  are  shown  in  Table  12-3. 
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Table  12-3 
Device-Specific  QIO  Functions  for  Communication  Interfaces 


Format 

Function 

0IO$C  lO.FDX 

Set   device   to   full-duplex   mode; 
Not  applicable  to  DAll-B 

0IO$C  lO.HDX,.. 

.  ,<stat,mode> 

SET  device   to   half-duplex   mode; 
Not  applicable  to  DAll-B 

QIOSC  lO.INL,.. 

» 

Initialize  device   and   set   device 
characteristics 

QIOSC  lO.RNS,.. 

.  ,<stadd,size> 

READ   logical    block,    without 
stripping      sync      characters 
(transparent  mode);   Not  applicable 
to   DQll;    for   DAll-B   and  DMCll, 
treated  like  lO.RLB 

QIOSC  lO.SYN,.. 

. ,<syn> 

SPECIFY  sync  character;   not 
applicable  to  DAll-B  or  DMCll 

QIOSC  lO.TRM,.. 

■ 

Terminate  commjnication, 
disconnecting  from  physical  channel 

QIOSC  lO.WNS,., 

. ,<stadd,size> 

WRITE    logical     block    without 
preceding      sync      characters 
(transparent  mode);   for  DAll-B  and 
DMCll.  treated  like  lO.WLB 

stadd 


size 


syn 


The  starting  address  of   the  data   buffer   (may  be  on  a   byte 
boundary) . 


The  data  buffer  size  in  bytes  (must  be  greater  than  0) 


The  sync  character,  expressed  as  an  octal  value. 


Stat 


mode 


The  station  assignment  (primary  or  secondary) 


The  transmission  mode  (normal  or  maintenance) 


The  device-specific  functions  listed  in  Table  12-3   are  described   in 
greater  detail  below. 
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12.3.2.1  lO.PDX  -  The  lO.FDX  QIO  function  is  used  to  set  the  mode  on 
a  DLll-E,  DPll,  DQll,  DUll,  DUPll,  or  DMCll  unit  to  full-duplex.  The 
lO.FDX  function  code  can  be  combined  (ORed)  with  the  lO.SYN  function 
code,  if  desired,  to  set  the  operational  characteristics  of  the 
physical  device  unit. 


12.3.2.2  lO.HDX  -  The  lO.HDX  QIO  function  is  used  to  set  the  mode  on 
a  DLll-E,  DPll,  DQll,  DUll,  DUPll,  or  DMCll  unit  to  half-duplex.  The 
lO.HDX  function  code  can  be  combined  (ORed  together)  with  the  lO.SYN 
function  code,  if  desired,  to  set  the  operational  characteristics  of 
the  physical  device  unit. 


Setting  ha 
assignment 
mode  (MOP) 
included 
and  a  nonz 
if   both 
secondary 
stations, 
selects  no 
mode  canno 


If-duple 

(prima 

as  oppo 

in  optio 

ero  indi 

ends  are 

station. 

Option 

rmal  mod 

t  commun 


X  on  the  DMCl 
ry/secondary) 
sed  to  norma 
nal  QIO  param 
cates  seconda 
primary  stat 
It  does  no 
al  QIO  parame 
e  and  a  nonze 
icate  with  a 


1  also  involves  setting  the  station 
and  may  include  selecting  maintenance 
1  mode.  The  station  assignment  is 
eter  pi.  A  0  indicates  primary  station 
ry  station.  The  DMCll  works  properly 
ions  or  if  there  is  one  primary  and  one 
t  work  if  both  ends  are  secondary 
ter  p2  is  used  to  select  the  mode.  A  0 
ro  selects  MOP  mode.  A  DMCll  in  MOP 
DMCll  in  normal  mode. 


12.3.2.3  lO.INL  and  lO.TRM  -  These  two  QIO  functions  have  the  same 
function  code  but  different  modifier  bits.  lO.INL  is  used  to 
initialize  a  physical  device  unit  for  use  as  a  communications  link. 
It  turns  the  device  on  line,  sets  device  characteristics,  and  ensures 
that  the  appropriate  data  terminal  is  ready.  lO.TRM  disconnects  the 
device.  If  the  device  has  a  dial-up  interface,  it  also  hangs  up  the 
1  ine. 


12.3.2.4  lO.RNS  -  The  lO.RNS  QIO  function  is  used  to  read  a  logical 
block  of  data,  without  stripping  the  sync  characters  that  may  precede 
the  data.  A  similar  function  is  lO.RLB,  which  is  nontransparent ,  in 
that  it  causes  sync  characters  preceding  the  data  message  to  be 
stripped.  lO.RLB  is  used  at  the  start  of  a  segmented  data  request,  in 
which  the  block  might  have  the  following  layout: 


s 

s 

H 

H 

H 

H 

CS 

CS 

DATA 

CS 
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H 


CS 


A  sync  character, 


A  header  character. 


A  validity  check  character. 
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The  programmer  must  strip  sync  characters  from  the  beginning  of  a  data 
block  in  this  way.  Stripping  only  at  the  beginning  of  a  read  allows  a 
later  character  which  happens  to  have  the  same  binary  value  as  a  sync 
character  to  be  read  without  stripping.  lO.RLB  is  used  to  read  a 
logical  block  with  leading  sync  characters  stripped;  lO.RNS  is  used 
to  read  the  block  without  stripping  leading  sync  characters.  Since 
the  DAll-B  is  a  parallel  device  and  there  are  no  sync  characters,  it 
treats  the  latter  as  if  it  were  lO.RLB.  Generally,  10. RLE  should  be 
used . 


12.3.2.5  lO.SYN  -  This  QIO  function  allows  the  programmer  to  specify 
the  sync  character  to  be  recognized  when  an  10. RLE  or  lO.WLB  function 
is  performed.  lO.SYN  can  be  combined  (ORed  together)  with  lO.HDX  or 
with  lO.FDX  to  set  the  characteristics  of  the  physical  device  unit. 


12.3.2.fi  lO.WNS  -  This  QIO  function  causes  a  logical  block  to  be 
written  with  no  preceding  sync  characters.  To  ensure  that  the  two 
systems  involved  in  a  communication  are  synchronized,  two  or  more  sync 
characters  are  transmitted  by  one  system  and  received  by  the  other 
before  any  other  message  can  be  sent.  lO.WLB  is  used  to  write  a  block 
of  data,  preceded  by  sync  characters;  lO.WNS  is  used  to  perform  a 
block  transfer  without  sending  sync  characters  first.  Since  the 
DAll-B  is  a  parallel  device  and  there  are  no  sync  characters,  it 
treats  the  latter  as  if  it  were  lO.WLB.  Generally,  lO.WLE  should  be 
used . 


12.4   STATUS  RETURNS 


The  error  and  status  conditions  listed  in  Table  12-4  are 
the  communication  drivers  desciibed  in  this  chapter. 


returned   by 


Table  12-4 
Communication  Status  Returns 


Code 

Reason 

IS. sue 

Successful  completion 

The  operation  specified   in   the   QIO  directive   was 

completed   successfully.    The  second  word  of  the  I/O 

status  block  can  be  examined  to  determine  the   number 

of  bytes  processed,  if  the  operation  involved  reading 

or  writing. 

IS.PND 

I/O  request  pending 

The  operation  specified  in  the  QIO  directive  has   not 

yet   been   executed.    The  I/O  status  block  is  filled 

with  Os. 

(continued  on  next  page) 
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Code 


lE.BCC 


IE. CNR 


lE.DAO 


lE.DNR 
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Table  12-4   (Cont.) 
Communication  Status  Returns 


Reason 


Block  check  error 

When  the  Cyclic  Redundancy  Check  (CRC)  option  is 
present  on  the  DOH*  a  check  character  is  appended  to 
each  message  transmitted.  The  receiver  of  the 
messages  recalculates  the  check  character  and 
compares  it  with  the  one  transmitted.  This  error 
code  is  returned  when  the  two  check  characters  do  not 
match,  and  represents  a  transmission  error. 

Connection  rejected 

(DMCll  only.)  The  DMCll  has  detected  that  the  device 
on  the  other  end  of  the  line  has  restarted  itself. 
The  user  can  recover  by  issuing  lO.INL  (initialize), 
and  then  reissuing  the  QIO  in  question. 

Data  overrun 

Due  to  UNIBUS  traffic  or  a  modem  problem,  the  DQll 
controller  was  unable  to  maintain  the  data  rate 
required  to  prevent  data  loss  (that  is,  the  receipt 
of  another  byte  before  processing  of  a  previous  byte 
was  completed) . 

Device  not  ready 

The   physical   device   unit   specified   in   the  QIO 

directive   was  not   ready  to  perform  the  desired  I/O 

operation.  This  code  is  returned  to  indicate  one  of 
the  following  conditions: 

•   The  physical  device  unit  could  not  be   initialized 
(that  is,  the  circuit  could  not  be  completed). 
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the   receiv 
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time-out  does  not 
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transfer  is  initia 
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timing  out. 


er  was  not 
riod  of  time 
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time-out 

ress  and 

age 

does 

to 

this 

ize 

the 

the 

next 

ead 

If 

transfer 

device. 

it 

will 

ed 

byte 
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Table  12-4   (Cont.) 
Communication  Status  Returns 


Code 


Reason 


IE. IPC 


lE.OFL 


lE.SPC 


:e.ver 


IE. ABO 


lE.RSU 


lE.TMO 


Illegal  function 

A  function  code  was  specified  in  an  I/O  request  that 
is  illegal  for  message-oriented  communication 
devices. 

Device  off  line 

The  physical  device  unit  associated  with  the  LUN 
specified  in  the  QIO  directive  was  not  on  line.  When 
the  system  was  booted,  a  device  check  indicated  that 
this  physical  device  unit  was  not  in  the 
configuration. 

Illegal  address  space 

The  buffer  specified  for  a  read  or  write  request  was 
partially  or  totally  outside  the  address  space  of  the 
issuing  task.  Alternatively,  a  byte  count  of  0  was 
speci  f ied . 

Nonrecoverable  error  (DAll-B  only) 

The  data  transfer  terminated  before  all  of  the  data 
has  been  transmitted.  The  error  code  is  returned  on 
transmit  when  both  systems  attempt  to  transmit  at  the 
same  time.  This  condition  is  detected  by  the  device 
protocol.  The  error  code  is  returned  on  receive  when 
the  transmit  data  count  of  the  transmitting  side  does 
not  equal  the  data  count  specified  by  the  receive 
010. 

Operation  Aborted 

The  specified  I/O  operation  was  canceled  by  lO.KIL 
while  in  progress  or  while  still  in  the  I/O  queue. 

Sharable  Resources  in  use 

The  task  attempted  to  allocate  Unibus  Mapping 
Registers.  All  UMRs  were  allocated  to  other  tasks 
and  were  unable  to  complete  the  transfer. 

Timeout  Error 

The  physical  device  unit  associated  with  the  LUN 
specified  in  the  QIO  directive  timed  out.  This 
occurs  during  a  data  transfer  operation  when  the  task 
does  not  receive  an  interrupt  within  a  specified 
amount  of  time. 


12-10 


MESSAGE-ORIENTED  COMMUNICATION  DRIVERS 


12.5   PROGRAMMING  HINTS 


This  section  contains  information  on  important  programming 
considerations  relevant  to  users  of  the  message-oriented  communication 
interfaces  described  in  this  chapter. 


12.5.1  Transmission  Validation 


Because  there  is  no  way  for  the  transmitting  device  to  verify  that  the 
data  block  has  successfully  arrived  at  the  receiving  device  unless  the 
receiver  responds,  the  transmitter  assumes  that  any  message  that  is 
clocked  out  on  the  line  (without  line  or  device  outage)  has  been 
successfully  transmitted.  As  soon  as  the  receiver  is  able  to  satisfy 
a  read  request,  it  returns  a  successful  status  code  (IS.SUC)  in  the 
I/O  status  block.  Of  course,  only  the  task  receiving  the  message  can 
determine  whether  the  message  has  actually  been  transmitted 
accurately. 


The  receiving  device  should  be  ready  to   receive 
request)  at  the  time  the  transmission  is  sent. 


data   (wit.. 


read 


12.5.2  Redundancy  Checking 

By  the  nature  of  message-oriented  communications,  only  the  task  that 
receiver  a  communication  can  determine  whether  the  message  was 
received  successfully.  The  transmitter  simply  transfers  data,  without 
validation  of  any  kind.  It  is  therefore  the  responsibility  of  the 
communicating  tasks  which  use  the  device  to  check  the  accuracy  of  the 
transmission.  A  simple  validity  check  is  a  checksum-type  longitudinal 
redundancy  check.  A  better  approach  to  validatint^'  data  is  the  use  of 
a  cyclic  redundancy  check  (CRC) .  A  ORG  can  be  computed  in  software  or 
with  a  hardware  device,  such  as  the  KG-11  communications  arithmetic 
option. 


Both  D.:ll  and  DUPll  incorporate  hardware  to  compute  a  CRC. 
CRC  hardware  requires  an  extra  system  unit. 


The   DQll 


12.5.3  Half-Duplex  and  Full-Duplex  Considerations 

Because  there  is  a  single  I/O  request  queue,  only  one  QIO  request  can 
be  performed  at  a  time.  It  is  therefore  not  possible,  through  QIOs, 
for  a  device  to  send  and  receive  data  at  the  same  time.  Also,  since 
timeouts  are  not  set  for  receive  functions,  a  receive  QIO  is 
terminated  only  by  receiving  a  message  from  the  remote  system,  or  by 
issuing  an  lO.KIL  QIO  for  the  device.  Therefore,  if  no  message  is 
transmitted  by  the  remote  system,  a  receive  w'll  not  terminate,  and  no 
further  I/O  can  be  performed  on  that  device  until  the  receive  is 
killed  by  issuing  an  lO.KIL  QIO. 

Both  half-duplex  and  full-duplex  lines  can  be  used  with  the  DLll-E, 
DMCll,  DPll,  DQll,  DUll,  and  DUPll.  The  mode  is  settable  by  using 
lO.FDX  for  full-duplex  and  lO.HDX  for  half-duplex.  In  half-duplex 
mode,  the  modem  signal  RTS  (Request  To  Send)  is  cleared  after  each 
"transmit  message."  In  full-duplex,  this  signal  is  always  left  on. 
Using  full-duplex  mode  eliminates  modem  delays  in  transmission,  but 
requires  full-duplex  hardware  and  communication  links. 
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Only  half-duplex  mode  is  available  with 
nature  of  the  hardware. 


the   DAll-B   because   of   the 


The  DMCll  Driver  maintains  both  transmits  and  receives  separately  in 
its  own  internal  queues.  Thus,  it  is  a  full-duplex  driver.  There  is 
no  limit  on  the  number  of  outstanding  I/O  requests  that  can  be  active 
at  any  given  time.  The  DMCll  hardware,  however,  allows  a  maximum  of 
only  seven  transmits  and  seven  receives  to  be  active  at  any  time.  The 
driver  gives  the  first  seven  transmits  (or  receives)  directly  to  the 
DMCll  and  queues  the  eighth  and  subsequent  transmits  (or  receives) 
internally  until  the  DMCll  acknowledges  a  successful  I/O  request. 
When  running  on  an  11/70,  the  driver  gives  only  two  transmits  (or 
receives)  to  the  DMCll  because  each  request  requires  a  UNIBUS  mapping 
register.  The  DMCll  driver  is  assigned  five  UMRs:  one  for  base 
table(s),  two  for  active  transmits,  and  two  for  active  receives. 


12.5.4   Low-Traffic  Sync  Character  Considerations 


a  line  is  low,  each  message  sent  from  a 
should  be  preceded  by  a  sync  train.  This 
to  resynchroni ze  if  a  message  is  "broken"  (that 
it  is  lost  in  transmission).  Correspondingly, 
by  a  communications  device  under  low-traffic 
conditions,  when  messages  are  not  contiguous  (back-to-back),  should  be 
read  with  an  lO.RLB  (read,  strip  sync)  function.  This  requires  that 
the  first  character  in  the  data  message  itself  not  have  the  binary 
value  of  the  sync  character. 


If  message  traffic  on 
communications   device 
enables  the  controller 
is,   part  or   all   of 
every  message  received 


12.5.5  Vertical  Parity  Support 

Vertical  parity  is  not  supported  by  the  DAll- 
DUll.   Codes  are  assumed  to  be  8-bit  only. 


B,  DLll-E,  DPll,  DOll,  or 


12.5.6  Powerfail  with  DMCll 


The  DMCll  currently  cannot  recover  after  a  power  failure  because  the 
RAM  in  its  internal  microprocessor  is  erased  when  power  fails.  Any 
I/O  requests  outstanding  at  the  time  of  a  power  failure  will  return 
IE. ABO.  These  requests  must  be  reissued  after  initializing  the  DMCll 
(lO.INL) . 


12.5.7   Importance  of  lO.INL 

After  the  type  of  communication  line  has  been  determined,  and  after 
lO.SYN  has  specified  the  sync  character,  it  is  extremely  important 
that  lO.INL  be  issued  before  any  transfers  occur.  This  ensures  that 
appropriate  parameters  are  initialized  and  that  the  interface  is 
properly  conditioned.  Note  that  10. INL  provides  the  only  means  of 
setting  device  characteristics,  such  as  sync  character.  For  this 
reason,  10. INL  should  always  be  used  immediately  prior  to  the  first 
transfer  ov^r  a  newly  activated  link. 
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Tasks  sending  messages  to  the  DMCl 1  should  begin  by  terminating  and 
reinitializing  the  device  (lO.TRM, 10. INL) . 1  lO.INL  must  be  issued 
after  each  lO.KIL  {which  effectively  kills  the  DMCl 1 ) ,  after 
power-fail,  and  upon  receipt  of  any  error  code. 


12.fi   PROGRAMMING  EXAMPLE 


The  following  exampie  ill'jstrates  the  initialization, 
device  parameters,  and  transmission  of  a  block  of 
message-oriented  communication  device. 


sett  ing 
data   on 


of 
a 


.MCALL   ALUNSS,0IOSS 


• 


ALUNSS  #1,#"XP,»0  ;  USE  LUNl  FOB  DPI  1 

QIOSS  #10. HDXIIO.SYN, <#:,,,, ,i226>   ;  SET  DEVICE  PARAMETERS 

OIOSS  #10. INL, #1  ;  PUT  DEVICE  ON  LINE 

OIOSS  »I0.WLB,»1, ,,<»TXSTP,#TXAST,#TXBUF,»100>;  SEND  A  BLOCK 


TXAST.    CMPB     •iS.SUCJ,377,§(SP)  + 


BEO      iOS 


WAS  DATA  CLf-XTKED  OU 

SOk.<  fiSSFULLV? 

ir  SO,  SET  UP  FOR  NEXT 

BLOCK 


1.  Note  that  this  will  cause  the  error  IE. CNR  to  be 
I/O  outstanding  on  the  other  end  of  the  line. 


returned   on  any 
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CHAPTER  13 
PCLll  PARALLEL  COMMUNICATIONS  LIMX  DRIVERS 


13.1   INTRODUCTION 

PCLll   Parallel   Communica 
RSX-llfl-PLUS    systems   by 
transmitter  function   and 
function.    The   PCLll-B 
'^  ime  division  multiplexed 
computers  can  transfer  dat 
transmitter,  receiver,  and 
can   transfer   parallel   1 
section  of  a  separate  PCLl 
One   of  the  PCLll-B  units 
section  enabled  to  effect 
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13.1.1  PCLll-B  Hardware 

Each  PCLll-B  transmitter  and  receiver  section  has  a   un 
address   (hardware-configured) .   When  a  master  section 
places  a  transmitter  address  on  the  TDM  bus   for   a   per 
called   a   timeslice.   During  the  timeslice,  the  address 
can  address  the  desired  receiver  section  and  transmit  on 
transmitter   waits   for   the   receiver   to   acknowledge 
indication  that  the  word  was  not   accepted.    If   the 
accepted,   it  will  normally  retransmit  the  word  on  the 
timeslice.   Thus,  a  message  up  to  32k  words  long  can  be 
a   receiver   one  word  at  a  time  during  the  time  in  which 
TDM  transactions  are  multiplexed  for  other  PCLll-B  devic 


ique  TDM  bus 
is  enabled,  it 
iod  of  time, 
ed  transmitter 
e  word;  the 
the  word  or  an 

word  is  not 
next  available 
transmitted  to 

other  similar 
es. 


13.1.2   PCLll  Transmitter  Driver 

The  PCLll  transmitter  driver  provides  two  basic  functions.  First,  it 
must  receive  data  sent  by  the  attached  task  and  store  it  in  a  silo 
buffer  in  the  PCLll  hardware.  Then,  the  driver  passes  proper  receiver 
address  and  command  information  to  the  PCLll  transmitter  hardware  to 
effect  the  actual  transfer  over  the  TDM  bus. 


13.1.3   PCLll  Receiver  Driver 

The  PCLll  receiver  driver  also  performs  two  basic  functions.  First, 
it  must  remove  data  from  the  receiver  silo  and  send  it  to  the 
connected  task.  In  addition,  the  receiver  driver  must  acknowledge  a 
transmitter  when  a  data  transmission  is  requested  by  that  transmitter. 
Subsequent  requests  by  other  transmitters  on  the  TDM  bus  are  ignored 
until  all  message  transactions  with  the  current  transmitter  are 
completed. 
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13.2   GET  LUN  INFORMATION  MACRO 

Word  2  of  the  buffer  filled  by  the  Get  LUN  Information  system 
directive  (the  first  characteristics  word)  contains  the  following 
information  for  the  PCLll  transmitter  and  receiver  drivers.  A  setting 
of  1  indicates  that  the  described  characteristics  is  true  for  PCLll 
transmitter  and  receiver  drivers. 

Meaning 

Record-oriented  device 

Carriage-control  device 

Terminal  device 

File-structured  device 

Single-directory  device 

Sequential  device 

Mass  storage  device 

User-mode  diagnostics  supported 

Device  supports  22-bit  direct  addressing 

Unit  software  write-locked 

Input  spooled  device 

Output  spooled  device 

Pseudo  device 

Device  mountable  as  a  communications  channel 

Device  mountable  as  a  FILES-11  volume 

Device  mountable 

Word  3  contains  device  driver-specific  information,  as  follows: 

Transmitter  driver: 

The  low  byte  of  word  3  contains  the  number  of  transmit  retries 
remaining  after  completing  the  current  data  transmit  function  if 
the  current  data  transmit  function  attempt  is  not  accepted  by  the 
addressed  receiver.   The  hfgh  byte  of  word  3  is  undefined. 

Receiver  driver: 

The  low  byte  of  Word  3  contains  the  index  of  the  current  state  of 
the  receiver  driver.  These  states  are  primarily  used  for 
diagnostic  purposes  and  are  defined  as  follows: 

Index  Value  Meaning 

0  No  task  is  connected. 

+2  Task  connected  but  not  triggered. 

+4  Task   triggered   and   waiting   for   lO.RTF  or 

lO.ATF  function. 
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Bit 

Setting 

1 

0 

0 

0 

0 

1 

6 

0 

7 

0 

8 

0 

9 

0 

10 

0 

11 

0 

12 

0 

13 

0 

14 

0 

15 

0 
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Index  Valu* 
+6 

-2 
-4 

-6 


Meaning 

Task  triggered  and  timed  out  while  waiting  for 
lO.RTF  or  lO.ATF  function. 

lO.ATF  function  is  in  progress. 

Task  connected,   not   triggered,   and   has   an 
lO.ATF  function  in  progress. 

An  lO.RTF  function  is  in  progress. 


The  high  byte  of  word  3  is  undefined.  Word  4  is  undefined.  Word  5  is 
the  default  buffer  size  in  bytes.  For  the  PCLll,  this  value  is  64 
bytes . 


13.3   QIO  MACRO  —  PCLll  TRANSMITTER  DRIVER  FUNCTIONS 

13.3.1   Standard  QIO  Functions 

Table  13-1  lists  the  standard  functions  of   the   QIO  macro   that   are 
valid  for  the  PCLll  transmitter  driver. 


Tabl«  13-1 
Standard  QIO  Functions  for  PCLll  Transmitters 


Format 

Function 

OIOSC  lO.ATT,... 
QIOSC  lO.DET,... 
QIOSC  lO.KIL,... 

Attach  device 
Detach  device 
Cancel  I/O  request 

13.3.2  Device-Specific  QIO  Functions 


Table  13-2  lists  the  device-specific  functions  of  the  QIO  macro   that 
are  valid  for  the  PCLll  transmitter  driver. 


Table  13-2 
Device-Specific  QIO  Functions  for  PCLll  Transmitters 


Format 

Function 

OIOSC  lO.ATX,. . . ,<stadd,size, 
f lagwd , id, retries, ret add> 

OIOSC  10. SEC,..., 

OIOSC  lO.STC, . . . ,<stadd,size, 
(state! , [mode] , ,retadd> 

Attempt  message  transmission 
Sense  master  section  status 

Set  master  section  characteristics 
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stadd 

The  starting  address  of  a  data   buffer.    (Its  description  and 
function  is  dependent  upon  the  specific  QIC  function.) 


sii* 


The  data  buffer  size  in  bytes.   (Its  description  and  function   is 
dependent  upon  the  specific  QIO  function.) 


flagtfd 


Id 


The  value  of  the  flagword  that  is  to  precede  the  message  being 
sent.  The  flags  specify  the  desired  receiver  function  as  defined 
by  the  user's  protocol. 


The  Identifier  of  the  CPU  to  which  the  message  is  to  be  sent. 
This  identifier  Is  the  desired  receiver's  TDM  bus  address.  It 
appears  in  the  high  byte  of  the  first  word  of  the  master  -section 
I/O  status  block.  The  identifier  number  is  an  octal  value 
contained  in  the  high  byte  of  the  parameter  word.  For  example, 
receiver  number  1  is  specified  as  400,  receiver  number  2  is 
specified  as  1000,  and  so  forth. 


retries 


The  number  of  retries  that  will  be  attempted,  following  the  first 
attempt,  that  will  be  performed  if  the  first  attempt  Is 
unsuccessful,  or  upon  detecting  transmission  errors  or  master 
down  conditions,  before  returning  error  status  to  the  calling 
task. 


retadd 

The  starting  address  of  a  7-word  buffer  into  which  the  contents 
of  the  six  transmitter  registers  and  the  transmitter 
master/maintenance  register  are  moved  prior  to  returning  to  the 
calling  task.  Information  describing  the  contents  of  these 
registers  can  be  obtained  by  referring  to  the  hardware 
documentation  supplied  with  the  PCLll  option. 

Stat* 

The  desired  state  setting  for  the  transmitter,  as  follows: 

Parameter 

Specified  State 

SS.MAS  TDM  bus  master 

SS.NBU  Neutral  (default  state) 
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nod* 


The  desired  mode  setting  for  {  llocating  transmitter  cimeslices  on 
the  TDM  bus,  as  follows: 


Parameter 
Entered 

MS.AUT 

MS. ADS 


Mode 
Auto  addressing  (default  mode) 
Address  silo 


13.3.2.1 
message 
contained 
stadd   pa 
buffer  si 
value . 
the  recei 
the   mess 
task  uses 
parameter 


10. ATX  -  Thi 
to   a   specif 

in  a  data  bu 
rameter.    Th 
ze  specified 
The  flag word 
ving  task  wil 
age.    The  id 

this  address 
s  9.ie  as  prev 


s  I/O  function  requests  an  attempt  to  transmit  a 
ied  CPU.  The  message  to  be  transmitted  is 
ffer  starting  at  the  address  specified  in  the 
is  address  must  be  on  a  word  boundary.  The  data 
in  the  size  parameter  must  be  an  even,  positive 
parameter  contains  user-defined  information  that 
1  use  in  determining  whether  to  accept  or  reject 
parameter  is  the  receiver  TDM  bus  address.  The 
to  direct  a  message  to  a  specific  CPU.  Other 
iously  described. 


13.3.2.2  10. SEC  -  This  I/O  function  is  used  to  sense  the  master 
section  status.  Upon  successful  completion  of  this  function,  the  I/O 
status  block  will  contain  a  typical  I/O  status  code  (IS.SUC)  return  in 
the  low  byte  of  the  first  word,  and  current  Transmitter 
Master/Maintenance  Register  (TMMR)  contents  in  the  second  word,  as 
follows : 


Status  Code 


Current  TMMR  Contents 


NOTE 

The  optional  isb  parameter  (see  Section 
1.5.1)  must  be  included  in  this  QIO 
request. 


13.3.2.3  lO.STC  -  This  I/O  function  sets  the  master  section 
operational  characteristics.  lO.STC  can  only  be  issued  by  a 
privileged  task.  Correct  use  of  the  function  depends  upon  the  current 
(or  specified)  operating  state  of  the  master  section  and  proper  use  of 
parameters.  Each  p^'ameter  is  used  as  described  in  the  following 
paragraphs.  Refer  to  all  paranieters  in  the  sequence  shown  for  a 
correct  interpretation  of  parameter  usage. 
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Stat*  —  The  state  parameter  determines  the  overall  function  of  this 
master  section  (and  transmitter  and  receiver  sections)  in  the  PCLll 
communications  link  as  it  relates  to  the  TDM  bus.  The  neutral  state 
(SS.NEU)  places  the  master  section  in  an  inactive  state  where  the  unit 
will  send  and  receive  messages  in  a  normal  manner,  but  the  master 
section  cannot  control  transmitter  timeslice  allocation  on  the  TDM 
bus.  The  master  state  (SS.MAS)  designates  this  unit  as  TDM  bus 
master,  enabling  control  of  transmitter  unit  timeslice  allotments  on 
the  TDM  bus;  only  on^  master  section  on  the  TDM  bus  can  be  designated 
TDM  bus  master. 

Mode  --  The  TDM  bus  master  can  allocate  transmitter  timeslices  In  one 
of  ttra  ways:  auto  address  mode  (HS.AUT)  or  address  silo  mode 
(MS. ADS).  When  operating  in  the  auto  address  mode  (MS.AUT),  which  is 
the  default  mode  for  the  TDM  bus  master,  equal  timeslice  allotments 
are  given  to  each  transmitter  unit;  transmitter  unit  addresses  are 
sequentially  put  on  the  TDM  bus  in  descending  order,  one  address  for 
each  timeslice.  When  operating  in  the  address  silo  mode,  transmitter 
unit  addresses  are  transmitted  in  a  uset -speci f ied  sequence,  allowing 
up  to  S0%  of  the  timeslices  to  be  allocated  to  one  transmitter  unit, 
if  desired. 

The  actunl  sequence  of  transmitter  timeslice  allocations  for  the 
address  silo  mode  is  set  up  in  the  user's  task  data  buffer  referenced 
by  the  stadd  parameter.  Certain  constraints  must  be  observed  when 
specifying  this  information,  as  follows: 

•  Each  entry  in  the  buffer  is  a  byte  containing  a  transmitter 
unit  address. 

•  At  least  20  entries,  but  not  more  than  50  entries,  must  be 
specified.  If  less  than  20  entries  are  specified,  the  driver 
will  repeat  the  entire  sequence,  as  specified,  in  order  to 
attain  the  required  minimum  of  20  addresses.  If  more  than  50 
addresses  are  specified,  no  change  in  timeslice  allocation 
will  be  effected  and  an  lE.VER  error  status  will  be  returned 
to  the  task. 

•  Identical  transmitter  addresses  in  either  adjacent  bytes  or  in 
first  and  last  bytes  should  be  avoided.  When  identical 
addresses  appear  in  adjacent  bytes  in  this  manner,  the  driver 
inserts  invalid  'pad"  transmitter  addresses  between  identical 
addresses,  effectively  resulting  in  no-operation  timeslices. 

•  Transmitter  addresses  are  decimal  values  ranging  from  1  to  32 
(inclusive)  which  correspond  to  addresses  implemented  on  the 
actual  transmitter  unit  hardware. 

•  The  size  parameter  must  correctly  specify  the  number  of 
address  bytes  contained  in  the  buffer  referenced  by  the  stadd 
parameter . 


13.4   PCLll  TRANSMITTER  DRIVER  STATUS  RETURNS 

Table  13-3  lists  PCLll  transmitter   driver   return   status   codes   and 
probable  reasons. 
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Table  n-3 
PCLll  Transmitter  Driver  Status  Returns 


Code 


Reason 


IS. sue 


IS,  TNC 


Successful  completion 

The  QIO  function  was  successfully  completed.  If 
an  10. ATX  function  was  completed,  the  second 
status  word  contains  the  number  of  bytes 
transferred;  the  message  was  not  truncated.  If 
an  10. SEC  function  was  completed,  the  second 
status  word  contains  the  current  contents  of  the 
master  section's  TMMR. 

Successful  transfer  but  message  truncated 

The  IO.n?X  function  was  completed,  but  the  message 
was  truncated  by  the  receiver  (the  receiver  buffer 
is  too  small).  The  transmitter  unit  cannot 
determine  how  many  words  were  tactual  ly  received  by 
the  receiver  unit;  the  second  word  of  the  I/O 
status  block  contains  the  length  of  the  requested 
transfer,  rather  than  tJie  actucl  count  of  words 
successfully  received  in  the  receiver's  buffer. 


IE. BAD 


lE.DNR 


Bad  parameter  specification 

A  bad  parameter  specification  was  included  in  the 
10. ATX  function,  or  an  invalid  state  parameter  or 
TDM  bus  timesllce  allocation  addressing  mode  was 
specified  in  the  lO.STC  function. 

This  error  status  is  also  returned  when  an  lO.STC 
function,  issued  to  a  TDM  bus  master  operating  in 
the  address  silo  mode,  refers  to  a  data  buffer 
containing  an  illegal  series  of  transmitter 
addresses.  An  illegal  series  of  addresses  occurs 
when  the  number  of  entries  specified  for  the 
timeslice  allocation,  plus  the  required  number  of 
pad  addresses,  either  exceeds  50  or  is  less  than 
0. 

Device  not  ready 

This  error  status  return  occurs  in  response  to  an 
10. ATX  function  when  one  of  the  following  occurs: 

•  Power  failure  in  this  CPU. 

•  Device  time-out  (no  response  from  the  addressed 
receiver) . 

•  Receiver  was  too  slow  in  accepting  or  rejecting 
the  transfer  request. 

•  The  master  section  is  inoperative.  This  error 
status  is  returned  only  after  the  number  of 
retries  specified  in  the  10. ATX  function  have 
been  attempted  without  success. 

(continued  on  next  page) 
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Table  13-3   (Cont.) 
PCLll  Transmitter  Driver  Status  Returns 


Code 

Reason 

lE.VER 

Unrecoverable  error 

The  lO.STC  function  state   setting   could   not   be 
achieved   because   the   task   is  not  privileged  or 
another  device  is  TDM  bus  master. 

lE.SPC 

Illegal  user  buffer 

The   buffer   address   specified   in    the    TO.ATF 
function   is  outside  of  the  issuing  task's  address 

space. 

lE.REJ 

Transfer  rejected 

The  data  transfer  request  specified  in  the   10. ATX 
function    was     rejected    by    the    addressed 
receiver--based  on  the  source  CPU   identifier   of 
the  task  issuing  the  request — and  flagword. 

lE.FLG 

Event  flag  already  specified 

An  event   flag   was  previously  specified   in   an 
lO.STC  function. 

lE.BBE 

Transmission  error 

This  error   status   is   returned   only  after   the 
number  of  retries  specified  in  the  10. ATX  function 
have   been   attempted   without   a   successful 
transmission.    (Cycle   redundancy  check  errors  or 
parity  errors  have  been  detected  on  each  attempt.) 

IE. ABO 

Request  terminated 

This   status   is   returned   when   a   pending    I/O 
function  has  been  aborted  in  response  to  an  lO.KIL 
function  being  issued  by  the  task. 

IE. IPC 

Illegal  function 

A  function  code  was  specified  in  an   I/O  request 
that  is  illegal  for  PCLll  transmitters. 

13.5   QIO  MACRO  ~  PCLll  RECEIVER  DRIVER  FUNCTIONS 

13.5.1   Standard  QIO  Functions 

Table  13-4  lists  the  standard  function  of  the  QIO  macro  that  is  valid 
for  the  PCLll  receiver  driver. 
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Table  13-4 
Standard  010  Functions  for  PCLll  Receivers 


Format 

Function 

OIOSC  lO.KIL,... 

Cancel  I/O  request 

13.5.2  Device-Specific  QIO  Functions 

Table  13-5  lists  the  device-specific  functions  of  the  QIC  macro   that 
are  valid  for  the  PCLll  receiver  driver. 


Table  13-5 
Device-Specific  QIO  Functions  for  PCLll  Receivers 


Format 

Function 

OIOSC  lO.CRX, . . . ,<tef ,bufadd> 

OIOSC  10. RTF,... 

OIOSC  lO.ATF,. . .,<stadd,size, 
retadd> 

OIOSC  lO.DRX,... 

CONNECT  for  reception 
Reject  transfer 

Accept  transfer 
Disconnect  from  reception 

t«f 


The  number  of  a  "trigger"  event  flag  that  will  be  set  whenever   a 
flagword  is  received  over  the  TDM  bus. 


bufadd 


The  address  of  a  2-word  buffer   containing   the   transmitter   id, 
trigger  status,  and  the  flagword. 


stadd 


The  address  of  a  data   buffer   to   receive   the  message, 
address  must  occur  on  a  word  boundary  (even  address) . 


This 


size 


The  data  buffer  size  in  bytes, 
even,  positive  value. 


The  size   specified  must  be  an 


retadd 


The  address  of  a  6-word  buffer  into  which  the  contents  of  the  six 
PCLll  receiver  hardware  registers  will  be  returned  upon 
successful  completion  of  the  function.  Information  describing 
the  contents  of  these  registers  can  be  obtained  by  referring  to 
the  hardware  documentation  supplied  with  the  PCLll  option. 
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13.5.2.1  lO.CRX  -  This  I/O 
receiver,  if  the  receiver  i 
When  connected,  this  task  i 
messages  by  means  of  the  rec 
(a  local,  common,  or  group-g 
message  is  pending.  It  i 
TDM  bus.  When  this  happens, 
connected  task  is  conside 
word  transmitted  by  a  transm 
the  receivet  unit. 

The  bufadd  parameter  must  be  included  in  this  I/O  function  to   specify 
the  address  of  a  2-word  block,  as  follows: 


function  connects  the 
s  not  currently  connec 
s  the  only  task  ca 
eiver  on  this  CPU.  Th 
lobal  event  flag)  info 
s  set  when  a  flagword 

a  significant  event  i 
red  "triggered."  The  f 
itter  when  attempting 


issuing 
ted  to  a 
pable  o 
e  trigge 
rms  the 
is  recei 
s  declar 
lag word 
to  send 


task  to  the 
nother  task, 
f  receiving 
r  event  flag 
task  when  a 
ved  over  the 
ed  and  the 
is  the  first 
a  message  to 


id 

sts 

f lagwd 

sts 


id 


The  current  trigger  status, 


The  identification  code  of  the  transmitter  attempting  to  send  the 
message. 

f lagwd 

The  flagword  transmitted  to  the  connected  receiver. 

Based  on  the  information  contained  in  the  flagword  and  the 
identification  code  of  the  transmitter  unit,  the  task  can  accept  or 
reject  the  transfer.  (Tvo  I/O  functions  are  provided  for  this 
purpose;  see  Sections  13.5.2.2  and  13.5.2.3.)  The  receiver  must 
respond  to  the  transmitter's  request  within  approximately  1.5  seconds; 
otherwise,  an  lE.DNR  error  status  is  returned  to  the  task  attempting 
the  transmission. 


13.5.2.2  10. RTF  -  This  function  informs  the  transmitter  device  that 
the  message  is  being  rejected  by  the  receiver.  Any  attempt  to  issue 
this  I/O  function  when  the  trigger  event  flag  is  not  set  will  be 
ignored,  and  nn  lE.NTR  error  status  will  te  returned  to  the  task. 


13.5.2.3  lO.ATF  -  This  function  informs  the  transmitter  device  that 
the  message  is  being  accepted.  Parameters  specify  both  the  data 
buffer  into  which  the  received  data  will  be  transferred,  and  the 
6-word  buffer  that  will  receive  the  contents  of  the  receiver  section 
hardware  registers  upon  successfully  completing  the  function. 

Unlike  the  10. RTF  function,  the  lO.ATF  function  can  be  issued  before 
the  task  is  triggered.  When  this  is  done,  the  lO.ATF  function  is 
queued  for  reception  of  any  flagword.  When  the  flagword  is  received, 
the  receiver  driver  immediately  executes  the  lO.ATF  function;  the 
connected  task  is  not  triggered  and  the  flagword  is  not  made  available 
to  the  task.  This  approach  is  useful  when  it  is  not  necessary  to 
examine  flagwords  or  to  accept  messages  based  on  the  source. 


13-10 


PCLll  PARALLEL  COMMUNICATIONS  LINK  DRIVERS 


13.5.2.4   lO.DRX  -  This  function  is  issued  by  a  task  to  disconnect  the 
receiver  for  use  by  other  tasks. 


13.fi   PCLll  RECEIVER  DRIVER  STATUS  RETURNS 


Table  13-fi   lists   PCLll   receiver  driver   return   status  codes   and 
probable  reasons. 


Table  n-6 
PCLll  Receiver  Driver  Status  Returns 


Code 

Reason 

IS. sue 

Successful  completion 

The  I/O  function  or  triggering   of   the   task   was 

successfully   completed.    When   this   status   is 

returned  upon  completion  of  the   lO.ATF   function, 

the   high-orde:   byte  of  the  first  word  in  the  I/O 

status  block  contains  the  identification   code   of 

the   transmitter   device   that   sent  the  flagword. 

The  second  word  of  the  I/O  status   block  contains 

the   number  of  bytes  transferred  over  the  TDM  bus. 

When  this  status  is  returned  as   a   result   of   an 

lO.CRX  function,  and  the  ••ask  being  triggered,  the 

I/O  status  block  contains  information  that  enables 

the   task   to   accept   or   reject  the  message  (see 

Section  13.5.2. 1) . 

IS.TNC 

Successful  transfer  but  message  truncated 

This  I/O  status  is  returned  when   the   message   is 

terminated    because   the   receiver   task   message 

buffer  specified  in  the   lO.ATF   function   is   too 

small   to  contain  the  message  being  received.   The 

second  word  of  the  I/O  status  word   contains   the 

number  of  bytes  successfully  transferred. 

IE. BAD 

Bad  parameter  specification 

A  bad  parameter  specification  was  included  in   the 

requested  function. 

lE.DNR 

Device  not  ready 

This  error  status  return  occurs  in  response  to   an 

10. RTF   or    lO.ATF   function   when   one   of   the 

following  occurs: 

•   Power  failure  in  this  CPU. 

<♦   Device  time-out   (no   r?sponse   from   addressed 

receiver)  . 

•   Receiver  was  too  slow  in  accepting  or  rejecting 

the  transfer  request. 

•   The  master  section  is  inoperative. 

(continued  on  next  page) 
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Table  13-6   (Cont.) 
PCLll  Receiver  Driver  Status  Returns 


Code 

Reason 

lE.SPC 

Illegal  user  buffer 

The  buffer   address   specified   in   the    lO.ATF 

function   is  outside  of  the  issuing  task's  address 

space. 

lE.DNA 

Task  not  connected  for  reception 

The  requested  function  cannot  be  executed   because 

the  task  is  not  connected  to  the  receiver. 

IE. DAG 

Data  overrun 

This  I/O  status  code  is  return*   when  the  task   is 

triggered,   but   the  previous  transfer  request  has 

neither  been  accepted  nor  rejected.   When  the  task 

issues  an  10. RTF  or  lO.ATF  function,  it  will  apply 

to  the  new  (most  recent)  flagword;    the   previous 

request  is  ignored. 

lE.DAA 

Device  already  connected  for  reception 

This  I/O  status  code  is  returned   in   response   to 

the   lO.CRX   function  when  the  receiver  Is  already 

connected  to  this  task  or   any  other   task.    No 

operation  is  performed. 

lE.NTR 

Task  not  triggered 

This  I/O  status  code   is   returned   when  a   task 

attempts   to  issue  an  10. RTF  function  prior  to  the 

task  being  triggered. 

lE.BBE 

Transr:  isdion  error 

This  error   status   is   returned   when   an   10. ^TF 

function   is   In   progress   and  a  cycle  redundancy 

check  error  or  parity  error  has  been  detected. 

IE. ABO 

Request  terminated 

This   status   is   returned   when   a   pending    i/0 

function  has  been  aborted  iii  response  to  an  lO.KIL 

function  being  issued  by  the  task. 

lE.FHE 

Fatal  hardware  error 

The  requested  function  cannot  be  executed   because 

of  a  hardware  failure. 

lE.IFC 

Illegal  function 

A  function  code  was  specified  in  an   I/O   request 

that  is  illegal  for  PCLll  transmitters. 
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AMALOG-TO-DIGITAL  CONVERTER  DRIVERS 


14.1   INTRODUCTION 

The  AFCll  and  ADOl-D  analog-to-digital  (A/D)  converters  are  used  to 
acquire  industrial  and  laboratory  analog  data.  (AFCll  and  ADOl-D 
driver  support  is  not  provided  on  RSX-llM-PLUS  systems.)  Although  each 
has  its  own  driver,  programming  for  both  is  quite  similar  and  both  are 
multichannel,  programmable  gain  devices.  The  ADOl-D  should  not  be 
confused  with  the  ADUOl,  a  UDC  module,  which  is  described  in  Chapter 
15.  Table  14-1  compares  the  AFCll  and  the  ADOl-D  briefly,  and 
subsequent  sections  describe  these  devices  in  greater  detail. 


Table  14-1 
Standard  Analog-to-Dig i tal  Converters 


AFCll 

ADOl-D 

Maximum  Sampling  Rate  (Points 
per  Second) 

Number  of  Bits 

Maximum  Number  of  Analog  Channels 
That  Can  Be  Multiplexed 

200  (20  per  single) 
channel 

13  or  14 

1024 

Approximately 

10,000 

10  or  11 
64 

14.1.1  AFCll  Analog-to-Dlgital  Converter 

The  AFCll  is  a  differential  analog  input  subsystem  for  industrial 
data-acquisition  and  control  systems.  It  multiplexes  signals,  selects 
gain,  and  performs  a  13-  or  14-bit  analog-to-digital  conversion  under 
program  control.  With  the  use  of  appropriate  signal-conditioning 
modules,  the  system  can  intermix  and  accept  low-level,  high-level,  and 
current  inputs,  with  a  high  degree  of  noise  immunity. 


14.1.2  ADOl-D  Analog-to-Digital  Converter 

The  ADOl-D  is  an  extremely  fast  analog  data-acquisition  system.  It 
multiplexes  signals,  selects  gain,  and  performs  a  10-  or  11-bit 
analog-to-digital  conversion  under  program  control.  The  ADOl-D  is 
normally  unipolar,  but  an  optional  sign-bit  facilitates  bipolar 
operation. 
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14.2   GET  LUN  INFORMATION  MACRO 


If  a  GET  LUN  INFORMATION  system  directive  is  issued  for  a  LUN 
associated  with  an  analog-to-digital  -^bLverter,  word  2  (the  first 
characteristics  word)  contains  all  Os,  words  3  and  4  are  undefined, 
and  word  5  is  not  significant,  since  there  is  no  concept  of  a  default 
buffer  size  for  analog-to-digital  converters. 


14.3   QIO  MACRO 

This  section  summarizes  standard  and  device-specific  QIO  functions  for 
analog-to-dig ital  ^converter  drivers. 


14.3.1  Standard  QIO  Function 

The  standard  function  that  is  valid  foi   analog-to-digital   converters 
is  shown  ir.  Table  14-2. 


Table  14-2 
Standard  010  Function  for  the  A/D  Converter 


Format 

Function 

QIOSC  lO.KIL,... 

Cancel  I/O  requests 

Since  all  requests  are  processed  within  a  small  amount  of  time,  no 
in-progress  request  is  ever  canceled.  This  function  simply  cancels 
all  queued  requests. 


14.3.2  Device-Specific  QIO  Function 

The  device-specific  function  of   the   QIO  macro   that   Is  valid   for 
analog-to-digital  converters  is  shown  in  Table  14-3. 


Table  14-3 
Device-Specific  QIO  Function  for  the  A/D  Converters 


Format 

Function 

0IO$C  lO.RBC, . . . ,<stadd,size,stcnta> 

INITIATE  .-nultiple  A/D 
conversions 

stadd 


The  starting  address  of  the  data  buffer   (must  be  on  a  word 
boundary) . 
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•  ise 


The  control  buffer  size  in  bytes  (must  be  even  and  greater   than 
0);   the  data  buffer  is  the  same  size. 


stcnta 


The  starting  address  of  the  control  buffer  (must  be  or.  a  word 
boundary) ;  each  control  buffer  word  must  be  constructed  as  shown 
in  Table  14-4. 


Table  14-4 
A/D  Conversion  Control  Word 


Bits 

Meaning 

AFC  11 

ADOl 

-D 

0-11 

Channel  number 

Range:   0-1023 

Range: 

0-63 

12-15 

Gain  value  for  thi 
sample,  expressed 
a  bit  pattern  as 
follows: 

15     14     13 

s 
as 

12 

Gain: 

Gain: 

0     0     0 

0 

1 

1 

0     0     0 

1 

2 

2 

0     0      1 

0 

illegal 

4 

0     0     1 

1 

illegal 

8 

0     1     0 

0 

10 

Illegal 

0      10 

1 

20 

Illegal 

0      1      1 

0 

i  1  legal 

Illegal 

0      1      1 

1 

illegal 

Illegal 

1      0      0 

0 

50 

illegal 

1      0      0 

1 

100 

illegal 

1      0      1 

0 

i  llegal 

Illegal 

1      0      1 

1 

illegal 

illegal 

1      1      0 

0 

200 

Illegal 

110 

1 

1000 

illegal 

1      1      1 

0 

illegal 

illegal 

1      1      1 

1 

illegal 

illegal 

14.4   FORTRAN  INTERFACE 

A  collection  of  FORTRAN-callable  subroutines  provide  FORTRAN  programs 
access  to  the  AFCll  and  the  ADOl-D.  These  are  described  in  this 
section.   All  are  reentrant  and  may  be  placed  in  a  resident  library. 


14.4.1   Synchronous  and  Asynchronous  Process  Control  I/O 

The  ISA  standard  provides  for  synchronous  and  asynchronous  I/O. 
Synchronous  I/O  is  indicated  by  appending  a  "W"  to  the  name  of  the 
subroutine  (for  example,  AISQ/AISQW) .  The  synchronous  call  suspends 
task  execution  until  the  I/O  operation  is  complete.  If  the 
asynchronous  form  is  used,  execution  continues  and  the  calling  program 
must  periodically  test  the  status  word  for  completion. 
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14.4.2  The  isb  Status  Array 

The  isb  (I/O  status  block)  parameter  Is  a  2-word  integer  array  that 
contains  the  status  of  the  FORTRAN  call,  in  accordance  with  ISA 
convention.   This  array  serves  two  purposes: 

1.  It  is  the  2-word  I/O  status  block  to  which  the  driver  returns 
a  status  code  on  completion  of  an  I/O  operation. 

2.  The  first  word  of  isb  receives  a  status  code  from  the  FORTRAN 
interface  in  ISA-compatible  format,  with  the  exception  of  the 
I/O  pending  condition,  which  is  indicated  by  a  status  of  0. 
The  ISA  standard  code  for  this  condition  is  +2. 

The  meaning  of  the  contents  of  isb  varies,  depending  on  the  FORTRAN 
call  that  has  been  executed;  but  Table  14-5  lists  certain  general 
principles  that  apply.  The  section  describing  each  subroutine 
provides  further  details. 


Table  14-5 
Contents  of  First  Word  of  isb 


Contents 

Meaning 

isb(l)  =  0 
isb(l)  =  1 
isb(l)  =  3 

3  <  isb(l)  <  300 
isb(l)  >  300 

Operation  pending;   I/O  in  progress 

Successful  completion 

Interface   subroutine    unable    to 
generate   QIO  directive,  or  number  of 
samples  is  0 

QIO  directive   rejected   and   actual 
error  code  =  -(isb(l)  -  3) 

Driver   rejected   request   and   actual 
error  code  =  -(isb(l)  -  300) 

Unless  otherwise  specified,  the  value  of  isb(2)  is  the  value  returned 
by  the  driver  to  the  second  word  of  the  I/O  status  block. 

FORTRAN  interface  subroutines  depend  on  asynchronous  system  traps  to 
set  their  status.  Thus,  if  the  trap  mechanism  is  disabled,  proper 
status  cannot  be  set. 


14.4.3   FORTRAN  Subroutine  Summary 

Table  14-6  lists  the  FORTRAN  interface  subroutines  supported   for   the 
AFCll  and  ADOl-D  under  RSX-llM. 
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Table  14-6 
FORTRAN  Interface  Subroutines  for  the  AFCll  and  ADOl-D 


Subroutine 

Function 

AIRD/AIRDW 

Perform  input  of  analog  data  in 
s  quence 

random 

AISQ/AISQW 

Read  a   series  of   sequential 
input  channels 

analog 

ASADLN 

Assign  a  LUN  to  the  ADOl-D 

ASAFLN 

Assign  a  LUN  to  the  AFCll 

The  following  subsections  briefly  describe  the  function  and  format  of 
each  FORTRAN  subroutine  call.  Note  the  use  of  ASADLN  and  ASAFLN  to 
assign  a  default  logical  unit  number. 


14.4.4   AIRD/AIRDW:  Performing  Input  of  Analog  Data  in  Random  Sequence 

The  ISA  standard  AIRD/AIRDW  FORTRAN  subroutines  input  analog  data   in 
random  sequence.   These  calls  are  issued  as  follows: 


CALL 


AIRD 


AIRDW 


(inm, icont, idata, [ isb] , [lun] ) 


inn 


The  number  of  analog  input  channels, 


icont 


An  integer  array  containing  terminal  connection  data-channel 
number  (right-justified  in  bits  0-11)  and  gain  (bits  12-15),  as 
shown  in  Table  14-4. 


idata 


Isb 


An  integer  array  to  receive  the  converted  values. 


A   2-word   integer   array   to  which   the  subroutine   status   is 
returned . 


lun 


The  logical  unit  number. 
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The  isb  array  has  the  standard  meaning  defined  in  Section  14.4.2.  If 
inm  ■  0,  then  isb(l)  ■  3.  The  contents  of  idata  are  undefined  if  an 
error  occurs. 


14.4.5  AISQ/AISQW:  Reading  Sequential  Analog  Input  Channels 

The  ISA  standard  AISQ/AISQW  FORTRAN  subroutines   read   a   series  of 
sequential  analog  input  channels.   These  calls  are  issued  as  follows: 

lAISO   I 
CALL  \       }         (inm, icont, idata,  [isbl , [lun] ) 
(aisqw  ' 

in* 

The  number  of  analog  input  channels. 

icont 

An  integer  array  containing  terminal  connection  data-channel 
number  ( right- just i fied  in  bits  0-11)  and  gain  (bits  12-15),  as 
shown  in  Table  14-4. 

idata 

An  integer  array  to  receive  the  converted  values. 

isb 

A  2-word  integer  array  to  which  the  subroutine  status  is 
returned . 


lun 


The  logical  unit  number. 


For  sequential  analog  input,  channel  number  is  computed  in  steps  of 
one,  beginning  with  the  value  specified  in  the  first  element  of  icont. 
The  channel  number  field  is  ignored  in  all  other  elements  of  the 
array. 

The  gain  used  for  each  conversion  is  taken  from  the  respective  element 
in  icont.  ''"hus,  even  though  the  channel  number  is  ignored  in  all  but 
the  first  element  of  icont,  the  gain  must  be  specified  for  each 
conversion  to  be  performed. 

The  isb  array  has  the  standard  meaning  defined  in  Section  14.4.2.  If 
inm  »  0,  then  isb(l)  =  3.  The  contents  of  idata  are  undefined  if  an 
error  occurs. 
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14.4.fi  ASADLNt  Assigning  a  LUN  to  the  ADOl-D 

The  ASADLN  FORTRAN  subroutine  assigns  the  specified  LUN  to  the  A.DOl-D 
and  defines  it  as  the  default  logical  unit  number  to  be  used  whenever 
a  LUN  specification  is  omitted  from  an  AIRD(W) /AISO(W)  subroutine 
call.   It  is  issued  as  follows: 

CALL  ASADLN  ( lun , [ isw] , [ iun] } 


lun 


isw 


lun 


The  logical  unit  number  to  be  assigned  to  the  ADOl-D  and   defined 
as  the  default  unit. 


An  integer  variable  to  which  the  result  of  the  ASSIGN  LUN   system 
directive  is  returned. 


The  unit  number  to  be  assigned.   If  unspecified,  a  value  of  0   is 
assumed . 


Only  the  LUN  specified  in  the  last  call  to  ASADLN  or  ASAFLN  is  defined 
as  the  default  unit. 


14.4.7   ASAFLN:  Assigning  a  LUN  to  the  AFCll 

The  ASAFLN  FORTRAN  subroutine  assigns  the  specified  LUN  to  the  AFCll 
and  defines  it  as  the  default  logical  unit  number  to  be  used  whenever 
a  LUN  specification  is  omitted  from  an  AIRD(W) /AISO (W)  subroutine 
call.   It  is  issued  as  follows: 

CALL  ASAFLN  { lun , f i sw] , [ i un ] ) 


lun 


isw 


The  logical  unit  number  to  be  assigned  to  AFCll   and   defined   as 
the  default  unit. 


An  integer  variable  to  which   the   status   from   the   ASSIGN   LUN 
system  directive  is  returned. 

i'jn 

The  unit  number  to  be  assigned.   If  unspecified,  a  value  of  0   is 
assumed . 

Only  the  LUN  specified  in  the  last  call  to  ASAFLN  or  ASADLN  is  defined 
as  the  default  unit. 
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14. S   STATUS  RETURNS 

Ttto  error  and  status  conditions  listed  in  Table  14-7  are   returned   by 
the  analog-to-digital  converter  drivers  described  in  this  chapter. 


Table  14-7 
A/D  Converter  Status  Returns 


Code 


IS. sue 


IS.PND 


IE. ABO 


IE. BAD 


IE. BYT 


lE.DNR 


Reason 


Successful  completion 

The  operation  specified  in  the  010  directive  was 
completed  successfully.  The  second  word  of  the  I/O 
status  block  can  be  examined  to  determine  the  number 
of  A/D  conversions  performed. 

I/O  request  pending 

The  operation  specified  in  the  010  directive  has  not 
yet  been  executed.  The  I/O  status  block  is  filled 
with  Os. 


Operation  aborted 

The  specified  I/O  operation  was  canceled  with 
while  still  in  the  I/O  queue. 


lO.KIL 


Bad  parameter 

An  illegal  specification  was  supplied  for  one  or  more 
of  the  device-dependent  QIO  parameters  (words  fi-11). 
For  the  analog-to-digital  converters,  this  code 
indicates  that  a  bad  channel  number  or  gain  code  was 
specified  in  the  control  buffer. 

Byte-aligned  buffer  specified 

Byte  alignment  was  specified  for  a  data  or  control 
buffer,  but  only  word  alignment  is  legal  for 
analog-to-digl tal  converters.  Alternatively,  the 
length  of  the  data  and  control  buffer  is  not  an  even 
number  of  bytes. 

Device  not  ready 

The  physical  device  unit  specified  in  the  QIO 
directive  was  not  ready  to  perform  the  desired  I/O 
operation.  For  the  AFCl 1 ,  this  code  is  returned  if 
an  interrupt  time-out  occurred  or  the  power  failed. 
In  the  case  of  the  ADOl-D,  which  is  not  operated  in 
interrupt  mode,  this  code  indicates  a  software 
time-out  occurred  (that  is,  a  conversion  did  not 
complete  within  30  microseconds)  . 


(continued  on  next  page) 
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T«bl«  14-7   (Cont.) 
A/D  Converter  Status  Returns 


Code 

Reason 

IE. IPC 

Illegal  function 

A  function  code  was  specified  in  an  I/O  request 

that 

is  illegal  for  analog-to-digital  converters. 

lE.OFL 

Device  off  line 

The  physical  device   unit   a-'isocidted   with   the 

LUN 

specified  in  the  QIC  directive  was  not  on  line. 

When 

the  system  was  booted,  a  device  check  indicated 

that 

this   physical   device   unit   was   not    in 

the 

configuration. 

lE.SPC 

Illegal  address  space 

The  data  or  control  buffer  specified  for  a  conversion 

request   was  partially  or  totally  outside  the  address 

space  of  the  issuing  taslc.   Alternately,  a  byte 

count 

of  0  was  specified. 

FORTRAN  interface   values   for   these   subroutines   are   presented   in 
Section  14.5.1. 


14.5.1   FORTRAN  Interface  Values 

The  values  listed  in  Table  14-8  are   returned   in   FORTRAN  subroutine 
cal Is. 


Table  14-8 
FORTRAN  Interface  Values 


Status  Return 

FORTRAN  Value 

IS. sue 

+01 

IS.PND 

+00 

I  E.ABO 

+  315 

lE.ADP 

+  101 

IE. BAD 

+  301 

IE. BYT 

+  319 

I E . DAO 

+  313 

I E . DNR 

+  303 

lE.IEF 

+  100 

lE.IFC 

+  302 

lE.ILU 

+  99 

IE. NOD 

+  323 

lE.ONP 

+  305 

lE.PRI 

+  316 

lE.RSU 

+  317 

lE.SDP 

+  102 

lE.SPC 

+  306 

lE.ULN 

+  08 

lE.UPN 

+  04 
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14. fi   FUNCTIONAL  CAPABILITIES 

The  APCl 1  and  ADOl-D  operate  only  in  multisample  mode,  because  the 
user  can  simulate  single-sample  mode  by  simply  specifying  one  sample. 
Multisample  mode  permits  many  channels  to  be  sampled  at  approximately 
the  same  time  without  requiring  the  user  to  queue  multiple  I/O 
requests. 

The  maximum  number  of  channels  in  the  configuration  is  specified  at 
system-generation  time.  This  value  is  stored  in  the  respective  APCll 
and  ADOl-D  unit  control  blocks. 


14.6.1  Control  and  Data  Buffers 

The  user  must  define  two  buffers  of  equal  size:  the  control  buffer 
and  the  data  buffer.  The  former  contains  the  control  words  needed  to 
perform  one  A/D  conversion  per  channel  specified.  Each  control  word 
indicates  the  channel  to  be  sampled  and  the  gain  to  be  applied  (see 
Table  14-4)  . 

The  data  buffer  receives  the  results  of  the  conversions.  Each  result 
is  placed  in  the  data  buffer  location  that  corresponds  to  the  control 
word  that  specified  it. 


14.7   PROGRAMMING  HINTS 

This  section  contains  information  on  important  programming 
considerations  relevant  to  users  of  the  analog-to-digital  converter 
drivers  described  in  this  chapter. 


14.7.1   Use  of  A/D  Gain  Ranges 

Note  that  the  A/D  gain  ranges  overlap.  The  key  to  successful  use  of 
the  A/D  converters  is  to  change  to  a  higher  gain  whenever  a  full-scale 
reading  is  imminent,  and  to  change  to  a  lower  gain  whenever  the  last 
A/D  value  recorded  was  less  than  half  of  full  scale.  This  method 
maintains  maximum  resolution  while  avoiding  saturation. 


14.7.2   Identical  Channel  Numbers  on  the  APCll 

When  requesting  sampling  of  more  than  one  channel,  the  user  should  not 
specify  multiple  sampling  of  a  single  channel  without  10  or  more 
intervening  samples  on  other  channels.  This  ensures  50  milliseconds 
between  samples  on  a  single  channel.  If  sampling  occurs  more  often 
than  this  on  a  single  channel,  partial  results  are  returned  (see 
Section  14.7.3) . 
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14.7.3  APCll  Sanpling  Rat* 

Although  the  APCll  can  sample  a  maximum  of  200  points  per  second,  a 
single  channel  can  only  be  sampled  at  20  points  per  second.  Because 
the  channel  capacitor  needs  50  milliseconds  to  recharge  after  each 
conversion,  more  frequent  sampling  may  result  in  partial  readings.  If 
this  occurs,  the  user  will  receive  no  indication  that  information  is 
being  lost.  To  ensure  that  information  is  not  lost  on  any  one 
channel,  the  user  should  sample  approximately  10  other  channels  before 
returning  to  the  first  one. 


14.7.4  Restricting  the  Number  of  ADOl-D  Conversions 

The  ADOl-D  is  an  extremely  fast  device,  providing  a  25-microsecond 
conversion  rate,  and  is  driven  programmably  to  minimize  system 
overhead.  However,  an  excessive  number  of  conversions  in  a  single 
request  essentially  locks  out  the  rest  of  the  system,  because  the 
driver  does  not  return  control  to  the  system  until  it  has  finished  all 
the  specified  conversions.  No  other  task  can  run,  although  interrupts 
can  still  occur  and  are  processed. 
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15.1   INTRODUCTION 

The  UDCll  Is  a  digital  input/output  system  for  industrial  and  process 
control  applications.  It  interrogates  and/or  drives  up  to  252 
directly  addressable  digital  sense  and/or  control  modules.  The  UDCll 
operates  under  program  control  as  a  high-level  digital  multiplexer, 
interrogating  digital  inputs  and  driving  digital  outputs.  (UDCll 
driver  support  is  not  provided  on  RSX-llM-PLUS  systems.) 

The  UDC  driver  will  support  either  the  UDCll  or  ICSll  subsystem.  The 
ICSll  (Industrial  Control  Subsystem)  operates  as  an  input/output 
device  that  is  functionally  similar  to  the  UDCll.  A  maximum  of  16  I/O 
modules  can  be  placed  in  one  ICSll  subsystem;  up  to  12  ICSlls  can  be 
interfaced  to  one  computer  system.  The  ICSll  subsystem  is  also 
supported  by  the  ICS/ICR-11  driver  described  in  Chapter  18.  The 
reader  should  consult  that  chapter  for  a  comparison  of  driver 
features. 

While  performing  analog-to-digital  conversions,  the  UDCll  driver  can 
handle  other  functions,  such  as  contact  or  timer  interrupts  or 
latching  output.  These  functions  are  performed  immediately,  without 
requiring  any  in-progress  analog-to-digital  conversions  to  first  be 
completed. 

Unlike  other  RSX-llM  I/O  device  drivers,  the  UDCll  driver  is  neither  a 
multicontroller  nor  a  multiunit  driver. 


15.1.1  Creating  the  UDCll  Driver 

Each  installation  must  assemble  the  driver  source  module  with  a  prefix 
file  that  defines  the  particular  hardware  configuration.  The  prefix 
file  is  created  during  system  generation  according  to  the  user's 
response  to  questions  relating  to  the  UDCll.  This  file  is  named 
RSXMC.MAC  and  includes  symbolic  definitions  of  the  UDCll 
configuration.  These  definitions  encode  the  relative  module  number 
and  the  number  of  modules  for  each  generic  type  specified  in  the 
system  generation  dialog.   The  encoding  has  the  following  format: 


8 

8 

number  of  modules 

starting  module  number 
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On*  or  more  of  the  following  symbols  is  generated: 

Synbol  Nodule  Type 

U$$ADM  Analog  input 

U$$AOM  Analog  output 

USSCIM  Contact  interrupt 

U$$CSM  Contact  sense  input 

U$$LTM  Latching  digital  output 

U$$SSM  Single-shot  digital  output 

U$$TIM  Timer  (I/O  counter) 

Note  that  all  modules  of  a  given  type  must  be   installed   together   in 
sequential  slots. 


15.1.2  Accessing  UDCll  Nodules 

RSX-llM  provides  two  methods  of  accessing  the  UDCll: 

1.  A  QIO  macro  call  issued  to  the  driver 

2.  Restricted  direct  access  by  any  task  to   I/O  page   registers 
dedicated  to  the  UDCll 

The  first  method,  access  through  the  driver,  is  required  to  service 
interrupting  modules  and  to  set  and  record  the  state  of  latching 
digital  output  modules. 

The  second  method,  direct  access,  is  a  high-speed,  low-overhead  way  to 
service  noninterrupt ing  modules.  The  following  functions  may  be 
performed  in  this  manner: 

•  Analog  output 

•  Contact  sense  input 

e   Single-shot  digital  output 

e   Read  a  contact  interrupt  module 

•  Read  a  timer  module 


15.1.2.1  Driver  Services  -  The  driver  services  the  following  types  of 
modules : 

*  Contact  incerrupt 

*  Timer  (I/O  counter) 

*  Analog  input 

e   Latching  digital  output 

Contact  and  timer  interrupts  need  not  be  serviced  by  a  single  task. 
One  task  may  be  connected  to  contact  interrupts,  and  another  to  timer 
interrupts.  A  nonpr ivi'ieged  task  can  connect  to  either  or  both  of 
these  classes  by  providing  a  circular  buffer  to  receive  interrupt 
information  and  an  event  flag  to  allow  triggering  of  the  task  whenever 
a  buffer  entry  is  made. 
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15.1.2.2  Dlract  Access  -  A  global  common  block  within  the  I/O  page 
provides  restricted  direct  access  to  the  UDCll  device  registers.  In  a 
mapped  system,  the  length  of  the  block  is  set  to  prevent  access  to 
other  device  registers.  In  an  unmapped  system,  the  use  of  the  common 
block  is  optional,  unless  ISA  FORTRAN  calls  are  used.  The  ISA 
routines  rofier  symbolically  to  the  UCDll  registers,  and  thus  require 
the  use  of  global  common.  Section  15.4  explains  direct  access  more 
fully. 


15.2   GET  LUN  INFORMATION  MACRO 

If  a  GET  LUN  INFORMATION  system  directive  is  issued  for  a  LUN 
associated  with  the  UDCll,  word  2  (the  first  characteristics  word) 
contains  all  zeros,  words  3  and  4  are  undefined,  and  word  5  is  not 
significant,  since  there  is  no  concept  of  a  default  buffer  size  for 
universal  digital  controllers. 


15.3   QIO  MACRO 

This  section  summarizes  standard  and  device-specific  QIO  functions  for 
the  UDCll  driver.  In  issuing  them,  note  the  numbering  r-'-^ventions 
described  in  15.7.2. 


15.3.1  Standard  QIO  Function 


The  standard  function  that  is  valid  for  the  UDCll  is  shown   in  Table 
15-1. 


Table  15-1 
Standard  010  Function  for  the  UDCll 


Format 

Function 

0IO$C  lO.KIL,... 

Cancel  l/C    requests 

lO.KIL  cancels  all   queued   requests   and   disconnects  all   Interrupt 
connections,  but  does  not  stop  any  I/O  that  is  currently  in  progress. 


15.3.2  Device-Specific  QIO  Functions 

Table  15-2  summarizes  device-specific  QIO  functions  that  are  supported 
for  the  UDC12. 
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Table  15-2 
D«vicc-Specl f Ic  010  Functions  for  the  UDCll 


Per mat 

Function 

oiosc 

lO.CCI, 

. . . ,<stadd,sizb,tevf > 

CONNECT  a  buff }r  to  contact 
interrupts 

OIOSC 

lO.CTI, 

. . . ,<stadd,slzb,tevf ,arv> 

CONNECT  a  buffer  to  timer 
interrupts 

OIOSC 

lO.DCI, 

•  •  • 

Disconne(t  a  buffer  from 
contact  interrupts 

OIOSC 

10. DTI, 

•  •  • 

Disconnect  a  buffer  from  timer 
interrupts 

OIOSC 

lO.ITI, 

.  . .  ,<«in,  ic> 

INITIALIZE  a  timer 

OIOSC 

lO.MLO, 

. .  .,<opn,pp,dp> 

OPEN  or  close  latching  digital 
output  points 

OIOSC 

lO.RBC, 

. . . ,<stadd ,si  ze,stcnta> 

INITIATE  multiple  A/D 
conversions 

m 


Btadd 


The  starting  address  of  the   data   buffer   (must   be  on  a   word 
boundary) . 


sizb 


tevf 


arv 


le 


o?n 


The  data  buffer  size  in  bytes  (must  be  even  and  large  enough  to 
include  a  2-word  buffer  header  plus  one  data  entry;  the  buffer 
may  cross  a  4K  boundary) . 


The  trigger  event  flag  number. 


The  starting  address  of  the  table  of  initial/reset   values   (must 
be  on  a  word  boundary) . 


The  module  number, 


The  Initial  count, 


The  first  l/itchint}  digits,   output  point  number,  w'llch  must  be   on 
a  module  boundary  (evenly  divisible  by  If). 


15-4 


UNIVERSAL  DIGITAL  CONTROLLER  DRIVER 


PP 


The  l'>-bit  mask. 


4p 


The  data  pattern. 


size 


The  control  buffer  olze  in  bytes  (must  be  even  and 
0);   the  data  buffer  is  the  same  size. 


greater   than 


stcnta 


The  starting  address  of  the  control  buffer  (must  be  on  a  word 
boundary) ;  each  control  buffer  word  must  be  constructed  as  shown 
in  Table  15-3. 


The  following  sections  describe  the  functions  listed  in  Table  15-2. 


Table  15-3 
A/D  Conversion  Control  Word 


Bits 

Meaning 

ADUOl 

0-11 

Channel    number 

Range:    0-4095 

12-15 

Gain   value    for    this 
sample,    expressed   as 
a    bit   pattern   as 
follows: 

15      14      13      12 

Gain: 

0        0        0        0 

1 

0        0        0         1 

2 

0        0         10 

Illegal 

0         0         11 

Illegal 

0         10         0 

10 

0         10         1 

20 

0         110 

Illegal 

0         111 

Illegal 

10         0         0 

50 

10         0         1 

100 

10         10 

Illegal 

10         11 

Illegal 

lion 

200 

110         1 

1000 

1110 

Illegal 

1111 

Illegal 
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15.3.2.1  Contact  Interrupt  Digital  Input  (W73a  Modulas)  -  Digital 
input  and  change  of  state  information  from  contact  interrupt  modules 
is  reported  in  a  requester-provided  circular  buffer.  The  buffer 
consists  of  a  2-word  header,  followed  by  a  data  area  in  the  following 
format! 


1 

driver  index 

2 

user  index 

3 

entry 

4 

entry 

• 

e 

• 

e 

• 

• 

Whenever  a  change  of  state  occurs  in  one  or  more  contact  points,  an 
interrupt  is  generated.  The  UDCl 1  driver  gains  control,  determines 
whether  the  change  of  state  is  of  interest  (that  is,  a  contact  closure 
and  point  closing  (PCL)  is  set  on  the  module),  and  then  optionally 
makes  an  entry  in  the  data  area  of  the  buffer,  updates  the  index 
words,  and  sets  the  trigger  event  flag  of  the  connected  task. 

Each  entry  consists  of  five  words  in  the  following  format: 

Word  Contents 

0  Entry  existence  indicator 

1  Change-of-state  (COS)  indicator 

2  Module  data  (current  point  values) 

3  Module  number  (interrupting  module) 

4  Generic  code  (interrupting  module) 

The  driver  enters  data  in  the  location  currently  indicated  by  the 
driver  index.  This  pointer  can  be  considered  as  a  FORTRAN  index  into 
the  buffer;  that  is,  the  first  location  of  the  buffer  is  associated 
with  the  index  1.  The  beginning  of  the  data  area  is  the  location  of 
the  first  entry  (index  3).  Entries  are  made  in  a  circular  fashion, 
starting  at  the  beginning  of  the  data  area,  filling  in  order  of 
increasing  memory  address  to  the  end  of  the  data  area,  and  then 
wrapping  around  from  the  end  to  the  beginning  of  the  data  area. 

It  is  expected  that  the  connected  task  will  maintain  its  own  pointer 
(the  user  index)  to  the  location  in  the  buffer  where  it  is  next  to 
retrieve  contact  interrupt  data.  When  a  task  is  triggered  by  the 
driver,  it  should  process  data  in  the  buffer  starting  at  the  location 
indicated  by  its  pointer  and  continuing  in  a  circular  fashion  until 
the  two  pointers  are  equal  or  a  zero  entry  existence  indicator  is 
encountered.  Equality  of  pointers  means  that  the  connected  task  has 
retrieved  all  the  contact  interrupt  information  that  the  driver  has 
entered  into  the  buffer. 

The  entry  existence  indicator  is  set  to  nonzero  when  a  buffer  entry  is 
made.  When  a  requester  has  removed  or  processed  an  entry,  he  must 
clear  the  existence  indicator  in  order  to  free  the  buffer  entry 
position. 
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If  data  Input  occurs  in  a  burst  sufficient  to  overrun  the  buffer,  data 
is  discarded  and  a  count  of  data  overruns  is  incremented.  The  nonzero 
entry  existence  indicator  also  serves  as  an  overrun  indicator.  A 
positive  value  (-fl)  indicates  no  overruns  between  entries;  a  negative 
value  is  the  two's  complement  of  the  number  of  times  data  have  been 
discarded  between  entries. 

The  module  number  indicates  a  module  on  which  a  change  of  state  in  the 
direction  of  interest  has  been  recognized  for  one  or  more  discrete 
points.  The  direction  of  the  change  may  be  from  0  to  1  or  1  to  0, 
depending  on  the  PCL  (point  closing)  and  POP  (point  opening)  module 
jumpers.  The  change  of  state  (COS)  Indicator  specifies  which  point  or 
points  of  the  module  have  changed  state. 

The  bit  position  of  an  on-bit   in   the  COS   indicator   provides   the 

low-order   bits  (3-0)  of  a  point  number  and  the  module  number  provides 

the  high-order  bits  (15-4).   The  module  data   indicates   the   logical 

value  (polarity)  of  each  point  in  the  module  at  the  time  of  the 
interrupt. 

Contact  interrupt  data  can  be  reported  to  only  one  task.  The 
functions  lO.CCI  and  lO.DCI  in  Table  15-2  are  provided  to  enable  a 
task  to  connect  and  disconnect  fron  contact  interrupts.  If  the 
connection  is  successful,  the  second  word  of  the  I/O  status  block 
contains  the  number  of  words  passed  per  Interrupt  in  the  low-order 
byte  and  the  Initial  FORTRAN  Index  to  the  beginning  of  the  data  area 
in  the  high-order  byte. 

NOTE 

The  size  of  the  data   area  must   be   a 
multiple  of  the  entry  size. 


15.3.2.2  Timer  (W734  I/O  Counter  Modules)  -  A  timer  (I/O  counter) 
module  is  a  clock  that  is  initialized  (loaded),  counts  up  or  down,  and 
then  causes  an  Interrupt.  The  UDCll  driver  treats  such  modules  in  a 
way  similar  to  that  in  which  it  handles  contact  Interrupts.  The 
requester  provides  a  circular  buffer  similar  to  that  for  contact 
interrupts.  Each  entry  consists  of  four  words  in  the  following 
format : 

Word  Contents 

0  Entry  existence  Indicator 

1  Module  data  (current  value) 

2  Module  number  (interrupting  module) 

3  Generic  code  (interrupting  module) 
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Th«  lO.CTI  function  In  Table  15-2  enables  a  task  to  connect  to  timer 
interrupts.  The  table  of  initial/reset  values  is  used  to  initially 
load  the  timers  and  to  reload  them  on  interrupt  (overflow) .  The  table 
contains  one  word  for  each  timer  module.  The  contents  of  the  first 
word  are  used  to  load  the  first  module,  and  so  forth.  If  a  timer  has 
a  nonzero  value  when  it  interrupts,  it  is  not  reloaded,  so  that 
■elf-clocking  modules  and  modules  that  interrupt  on  half  count  can 
continue  counting  from  the  initial  value. 

The  10. DTI  function  in  Table  15-2  disconnects  a  task  from  timer 
Interrupts,  and  the  10. ITI  function  provides  the  capability  of 
initializing  a  single  timer.  Requests  to  initialize  a  counter  are 
valid  only  if  the  issuing  task  has  connected  a  buffer  for  receiving 
counter  interrupts. 

NOTE 

The  size  of  the   data   area   must   be   a 
multiple  of  the  entry  size. 


15.3.2.3  Latching  Digital  Output  (M685,  M803,  and  M805  Modules)  - 
Each  module  has  16  latching  digital  output  points.  The  lO.MLO 
function  in  Table  15-2  opens  or  closes  a  set  of  up  to  16  points.  Bit 
n  of  the  mask  and  data  pattern  corresponds  to  the  point  opn  +  n.  If  a 
bit  in  the  mask  is  set,  the  corresponding  point  is  opened  or  closed, 
depending  on  whether  the  corresponding  bit  in  the  data  pattern  is 
clear  or  set.  If  a  bit  in  the  mask  is  clear,  the  corresponding  point 
remains  unaltered. 


15.3.2.4  Analog-to-Digital  Converter  (ADUOl  Module)  -  Each  ADUOl 
module  has  eight  analog  input  channels.  The  lO.RBC  function  in  Table 
15-2  initiates  A/D  conversions  on  multiple  ADUOl  input  channels. 
Restrictions  on  maximum  sampling  rates  are  the  same  as  those  defined 
for  the  AFCll  in  Chapter  14. 

The  converted  analog  value  is  returned  as  12  bits,  lef t- justi f led ,  in 
a  16-bit  word  with  the  low-order  4  bits  set  to  0. 


15.3.2.5  ICSll  Analog-to-Digital  Converter  (lAD-IA  Module)  -  Each 
lAD-IA  Module  has  eight  analog  input  channels.  The  channel  capacity 
may  be  expanded  to  120  by  the  addition  of  IMX-IA  multiplexers.  Each 
multiplexer  adds  16  input  channels  to  the  converter.  Restrictions  on 
maximum  sampling  rates  are  the  same  as  those  defined  for  the  AFCll  in 
Chapter  14.  The  lAD-IA  module  preempts  eight  module  slots  regardless 
of  the  number  of  IMX-IA  multiplexers  installed. 

For  addressing  purposes,  each  converter  occupies  a  block  of  120 
channels.  Thus,  A/D  converter  0  is  addressed  by  referencing  channels 
0  through  119;  A/D  converter  1  is  addressed  by  referencing  channels 
120  through  239,  and  so  forth.  When  fewer  than  seven  multiplexers  are 
installed,  not  all  addresses  within  the  block  are  valid. 

The  converted  analog  value  is  returned  as  12  bits,  lef t- justi fied ,  in 
a  16-bit  word  with  the  low-order  4  bits  set  to  0. 
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IS. 4   DIRECT  ACCESS 

Section  15.1.2  describes  UDCll  functions  that  mAy  be  performed  by 
referencing  a  module  through  its  physical  address  in  the  I/O  page. 
Under  RSX-llM  such  access  is  accomplished  by  one  of  the  following 
methods : 

1.  A  privileged  task  or  any  task  running  in  an  unmapped  system 
has  unrestricted  access  to  the  I/O  page,  and  may  therefore 
access  each  module  hy  absolute  address. 

2.  Using  the  Task  Builder,  a  task  may  link  to  a  global  common 
area  ti^hose  physical  address  limits  span  a  set  of  locations  in 
the  I/O  page.  This  method  applies  to  either  a  mapped  or 
unmapped  system. 

The  latter  method  allows  a  task  to  be  transported  to  any  other  system 
simply  by  relinking.  Furthermore,  in  a  mapped  system  the  memory 
management  hardware  will  abort  all  references  to  device  registers 
outside  the  physical  address  limits  of  the  common  block. 

The  operations  required  to  implement  each  method  may  be  summarized  as 
f ol lows : 

1.  Unrestricted  access  to  the  I/O  page 

a.  An  object  module  is  created  that  defines  the  UDCll 
configuration  through  a  list  of  absolute  global  addresses 
and  addressing  limits  for  each  module  type. 

b.  The  object  module  is  included  in  the  system  library  file. 

c.  A  task  is  created  containing  the  appropriate  global 
references.  Such  references  are  resolved  when  the  task 
builder  automatically  searches  the  system  library  file. 

Steps  a  and  b  are  executed  once,  during  system  generation  (see  the 
RSX-1 IW  System  Generation  and  Management  Guide) .  Step  c  is  performed 
each  time  a  task  is  created  tHat  references  the  UDC12. 

2.  Access  to  the  I/O  page  through  a  Global  Common  Block 

a.  An  object  module  is  created  that  defines  the  UDCll 
configuration  through  a  list  of  relocatable  global 
addresses  and  addressing  limits  for  each  module  type. 

b.  The  object  module  is  linked,  using  the  Task  Builder,  to 
create  an  image  of  the  Global  Common  block  on  disk. 

c.  The  SET  command  is  used  to  define  a  common  block  that 
resides  on  the  I/O  page. 

d.  The  INSTALL  NCR  command  is  used  to  make  the  Global  Common 
Block  resident  in  memory. 

e.  A  task  is  created  containing  the  appropriate  global 
references.  Such  references  are  resolved  by  directing 
the  Task  Builder  to  link  the  task  to  the  common  block. 

Steps  a  through  d  are  executed  once,  during  system  generation.  Step  e 
is  performed  each  time  a  task  is  created  that  references  the  UDCll 
common  block.   The  following  paragraphs  describe  each  step  in  detail. 


15-9 


UNIVERSAL  DIGITAL  CONTROLLER  DRIVER 

15.4.1   Defining  the  UDCIl  Configuration 

The  source  module  UDCOM.MAC,^  when  assembled  with  the  proper  prefix 
file,  provides  global  definitions  for  the  following  parameters: 

e   The  starting  audress  of  each  module  type 

e   The  highest  point  number  within  a  given  module  type 

e   The  highest  module  number  within  a  given  module  type 

The  last  two  parameters  ire  absolute  quantities  that  may  be  used  to 
prevent  a  task  from  referencing  a  module  that  is  nonexistent  or  out  of 
1 imlts. 

By  means  of  conditional  assembly,  the  list  of  addresses  may  be  created 
as  Absolute  symbols  defining  locations  in  the  I/O  page,  or  as  symbols 
within  a  relocatable  program  section  to  be  used  when  building  and 
linking  to  the  UDCll  Global  Common  area. 


15.4.1.1  Assembly  .Procedure  for  UDCOM.MAC  -  UDCOM.MAC  is  assembled 
with  the  RSX-.IM  configuration  parameters  contained  In  the  file 
RSXMC.MAC. 

To  create  relocatable  module  addresses,  either  the  parameter  U$$DCM  or 
M$$MGE  must  be  defined.  M$$MGE  will  be  Included  in  RSXMC.MAC  If 
memory  management  was  specified  when  the  system  was  generated.  If 
not,  the  user  should  edit  the  file  to  Include  the  following 
def ini  t Ion  : 

USSDCM=0 

The  file  may  then  be  assembled  using  the  MCR  com.  and : 

>MAC  UDCOM,UDLST»ril, 101 RSXMC , UDCOM 

This  command  Invokes  the  MACRO-11  assembler,  which  processes  the  Input 
files  RSXMC.MAC  and  UDCOM.MAC  to  create  UDCOM. OBJ  and  UDLST.LST. 

To  create  absolute  module  addresses,  both  U$$DCM  and  MSSMGE  must  be 
undefined.  Edit  RSXMC.MAC,  If  necessary,  to  remove  definitions  and 
then  Invoke  the  MACRO-11  assembler  with  the  following  MCR  command: 

>MAC  UDCDF , UDLST= [11,10] RSXMC , UDCOM 

In  this  sequence  the  files  UDCDF. OBJ  and  UDLST.LST  are  created  from 
the  specified  source  modules.  UDCDF. OBJ  contains  the  module  addresses 
in  absolute  form. 


15.4.1,2   Symbols  Defined  by  UDCOM.MAC  -  This   section   lists    the 
symbolic  definitions  created  by  UDCOM.MAC. 


1.  This  module  resides  on  the  RK05  cartridge  of  the  RSX-llM  RK 
distribution  kit  labeled  EXECUTIVE  SOURCE.  For  RP  distribution  kits, 
ic  resides  on  the  RP  image.   The  file  is  located  under  UIC  [11,10]. 
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The  following  symbols  define  the  absolute  or  relocatable  address  of 
the  first  module  of  a  given  type: 

Symbol  Module  Type 

$.ADM  Analog  input 

S.AOM  Analog  output 

S.CIM  Contact  interrupt 

S.CSM  Contact  sense  input 

S . LTM  Latching  digital  output 

S.SSM  Single-shot  digital  output 

S.TIM  Timer  (I/O  counter) 

The  addresses  in  relocatable  form  are  defined  in  a  program  section 
named  UDCOM  having  the  attributes: 

REL  -  relocatable 
OVR  -  overlaid 
D   -  data 
GBL  -  global  scope 

Note  that  these  attributes  correspond  to  those  attached  to  a  named 
common  block  within  a  FORTRAN  program. 

In  either  the  absolute  or  relocatable  case,  individual  modules  are 
referenced  by  the  corresponding  symbolic  address  plus  a  relative 
module  index. 

The  following  symbols  define  the  highest  digital  point  within  a  module 
type  : 

Symbol  Module  Typt. 

PS.CIM  Contact  interrupt 

PS.CSM  Contact  sense  input 

PS. LTM  Latching  digital  output 

PS.SSM  Single-shot  digital  output 

The  highest  point  number  is  defined  relative  to  the  first  point  on  the 
first  module  of  a  specific  type.  For  example,  if  two  contact 
interrupt  modules  are  installed,  the  symbol  PS.CIM  will  have  an  octal 
value  of  37. 

The  following  symbols  define  the  highest  module  number  within  a  given 
module  type. 

Symbol  Module  Type 

MS. ADM  Analog  input 

MS.AOM  Analog  output 

MS.CIM  Contact  interrupt 

MS.CSM  Contact  sense  input 

MS. LTM  Latching  digital  output 

MS.SSM  Single-shot  digital  output 

MS. TIM  Timer  (I/O  counter) 

The  highest  module  number  is  defined  relative  to  the  first  module  of  a 
given  type.  Thus,  based  on  the  previous  example,  MS.CIM  will  have  a 
value  of  1. 
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15.4.2   Including  UDCl  Syabolic  Definitions  In  th*  System  Object 
Module  Library 

As  described  in  Section  IS. 4,  a  task  having  unrestricted  access  to  the 
I/O  page  may  reference  a  UDCll  module  by  absolute  address.  The  object 
module  UDCDP  contains  symbolic  definitions  of  absolute  module 
addresses  and  may  be  included  in  the  System  Object  Module  Library: 

SY: [1, IISYSLIB.OLB 

The  Task  Builder  automatically  searches  this  file  to  resolve  sny 
undefined  globals  remainiiig  after  all  input  files  have  been  processed. 

The  following  example  illustrates  the  procedure  for  Including  the  file 
UDCDF.OBJ  in  the  library: 

>SET  /UIC-fl,l] 

>LBR  SYSLIB/IN-(200,?00]UDCDF 

The  SET  MCR  command  is  issued  to  establish  the  current  UIC  as  [1,1]. 
Next,  the  RSXllM  Librarian  is  invoked  and  instructed,  through  the  use 
of  the  /IN  switch,  to  include  the  object  module  UDCDF.OBJ  in  the  file 
SYSLI3.0LB. 


15.4.3  Referencing  the  UDCll  through  a  Global  Common  Block 

The  following  sections  define  the  procedure  for  creating  a  Global 
Common  block  in  the  I/O  PAGE,  making  the  block  resident  in  memory,  and 
creating  a  task  that  references  UDCll  modules  within  the  block. 
Examples  are  given  for  both  mapped  and  unmapped  systems. 


15.4.3.1  Creating  a  Global  Common  Block  -  The  following  sequence 
illustrates  the  use  of  the  object  file  UDCOM.OBJ  to  create  a  disk 
image  of  the  global  common  area  in  a  mapped  system: 

>SET  /UIC-ri,ll 

>TKB 

TKB>UDCOM/MM,LP: , SY: UDCOM/PI/-HD- [ 200 , 2001 UDCOM 

TKB>/ 

ENTER    OPTIONS: 

TKB>PAR=>UDCOM:0:  1000 

TKB>STACK»0 

TKB>/ 

In  the  above  example,  a  current  UIC  of  fl,l)  is  established  and  the 
Tafk  Builder  is  initiated.  The  initial  input  line  to  the  Task  Builder 
specifies  the  following  files: 

e   A  core  image  output  file  to  be  named  UDCOM. TSK 

e  A  memory  map  output  to  the  line  printer 

e   A  symbol  table  file  to  be  named  UDCOM. STB 

All  files  reside  on  SY:  under  UIC  [1,11.  The  single  input  file 
UDCOM.OBJ,  containing  the  UDCll  address  definitions  as  relocatable 
values,  constitutes  the  input. 


15-12 


UNIVBR8AL  DIGITAL  CONTROLLER  DRIVER 

The  switches  specified  for   the   output   files  convey   the   following 
information  to  the  Task  Builder: 

/Mf4  indicates  that  the  core  image  of  the  common  block  will 
reside  on  a  system  with  Memory  Management. 

/PI       indicates  that  the  core  image  is  position   independent; 

that   is,   the  virtual  address  of  the  common  block  may 

appear  on  any  4K   boundary   within   a   task's   address 
■pace. 

/-HD  indicates  that  the  core  image  will  not  contain  a 
header.  A  header  is  only  required  for  a  core  image 
file  that  is  to  be  installed  and  executed  as  a    task. 

The  names  of  the  partition,  task  file,   and   symbol-table   files  must 
agree. 

The  STACK  option  must  be  used  to  eliminate  the  stack  space. 

The  following  sequence  illustrates  the  corresponding  procedure  for   an 
unmapped  system: 

>SET  /uic-ri,ii 

>TKB 

TKB>UDCOM/-MM,LP: ,SY: UDCOM/PI/-HD- [200, 200) UDCOM 

TKB>/ 

ENTER  OPTIONS: 

TKB>STACK-0 

TKB>PAR-UDCOM: 171000: 1000 

TKB>/ 

Again  the  task  builder  is  requested  to  produce  a  core  image  and  symbol 

table   file   under   the   UIC  [1,11,  and  a  map  file  on  the  line  printer 

from  the  input  file  UDCOM. OBJ.   The  output  file   switches   convey   the 
following  information: 

/-fr-  indicates  that  the  core  image  of  the  common  block   will 

reside  on  an  unmapped  system. 

/PI  Indicates  that  the  core  image  is  position  independent. 
In  an  unmapped  system,  the  core  image  is  fixed  in  the 
same  address  space  for  all  tasks;  however,  the  global 
symbols  defined  in  the  symbol  table  file  retain  the 
relocatable  attribute. 

/-HD  indicates  that  a  core  image  without  a  header  is  to  be 
created . 

The  PAR  option  specifies  the  base  and  length  of  the   common   area   to 

coincide  with   the   standard   UDCll   addresses  in  the  I/O  page.   All 

references  to  the  common  block  by  tasks  will  be  resolved   within   this 
region. 


15.4.3.2  Making  th«  Common  Block  Resident  -  The  following  SET  command 
creates  a  UDCll  common  block  residing  in  the  I/O  page  for  a  mapped 
system: 

>SET  /MAIN-UDCOM:7710:10:DEV 
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The  corrsspond Inq  command  In  an  unmapped  system  Is: 

>SET  /MAIN-UDCUM:1710: 10:DEV 

The  preceding  sequence  specifies  the  allocation  of  a  common  block  In 
the  I/O  page  whose  physical  address  limits  correspond  to  the  UDCll 
standard  locations.  Note  that  the  address  bounds  and  length  are 
defined  in  units  of  32  words. 

The  command 

>INS  ri.HUDCON 

declares  the  common  block  resident  in  the  system. 


15.4.3.3  Linking  a  Task  to  the  UDCll  Common  Block  -  A  task  may  access 
UDCll  modules  by  linking  to  the  common  block  as  follows: 

TKB>TASK , LP : -TASK . OBJ 

TKB>/ 

ENTER  OPTIONS: 

TKB>  COMMON«UDCOM:RW 

TKB>/ 

The  above  sequence  is  valid  for  either  a  mapped  or  unmapped  system. 
In  both  cases  the  Task  Builder  will  link  the  task  to  the  common  block 
by  resolving  references  to  the  Global  symbol  definitions  contained  in 
UDCOM.STB.  If  memory  management  is  present,  the  Executive  will  map 
the  appropriate  physical  locations  into  the  task's  virtual  addressing 
space  when  the  task  is  made  active. 


15.5   FORTRAN  INTERFACE 

A  collection  of  FORTRAN-callable  subroutines  provide  FORTRAN  programs 
access  to  the  UDC12.  These  are  described  in  this  section.  All  are 
reentrant  and  may  be  placed  in  a  resident  library. 

Instead  of  using  the  FORTRAN-callable  subroutines  described  in  this 
section,  a  FORTRAN  program  may  use  the  global  comiron  feature  described 
in  Section  15.4  to  reference  UDCll  modules  directly  in  the  I/O  page, 
as  shown  in  the  following  example: 

C 

C        UDCll  GLOBAL  COMMON 

C 

COMMON  /UDCOM/  ICSM ( 1 0) , lAO ( 1 0) 
C 
C        READ  CONTACT  SENSE  MODULE  1  DIRECTLY 


C 


ICS»ICSM(1) 


Note  that  the  position  of  each  module   type   must   correspond   to   the 
sequence  in  which  storage  is  allocated  in  the  common  statements. 


15-14 


UNIVERSAL  DIGITAL  CONTROLLER  DRIVER 


15.5.1   Synchronous  and  Asynchronous  Process  Control  I/O 


The  ISA  standard  provides  for  synchronous  and  asynchronous  process 
I/O.  Synchronous  I/O  is  indicated  by  appending  a  "W"  to  the  name  of 
the  subroutine  (for  example,  AO/AOW) .  But  due  to  the  fact  that  nearly 
all  UDCll  I/O  operations  are  performed  immediately,  in  most  cases  the 
"W"  form  of  the  call  Is  retained  only  for  compatibility  and  has  no 
meaning  under  RSX-llM.  In  the  case  of  A/D  input,  however,  the  "W" 
form  is  significant:  The  synchronous  call  suspends  task  execution 
until  input  is  complete.  If  the  asynchronous  form  is  used,  execution 
continues  and  the  calling  program  must  periodically  test  the  status 
word  for  completion. 


15.5.2  The  inb  Status  Array 

The  isb  (I/O  status  block)  parameter  is  a  2-word  integer  array  that 
contains  the  status  of  the  FORTRAN  call,  in  accordance  with  ISA 
(Instrument  Society  of  America)  convention.  This  array  serves  two 
purposes: 

1.  It  Is  the  2-word  I/O  status  block  to  which  the  driver  returns 
an  I/O  status  code  on  completion  of  an  I/O  operation. 

2.  The  first  word  of  Isb  receives  a  status  code  from  the  FORTRAN 
Interface  in  ISA-compatible  format,  with  the  exception  of  the 
I/O  pending  condition,  which  is  Indicated  by  a  status  of  0. 
The  ISA  standard  code  for  this  condition  is  +2. 


The  meaning  of  the  contents  of  isb  varies,  depending  on  the  FORTRAN 
call  that  has  been  executed;  but  Table  15-4  lists  certain  general 
principles  that  apply.  The  section  describing  each  subroutine  gives 
more  details. 

In  some  cases,  the  values  or  states  of  points  being  read,  pulsed,  or 
latched  are  returned  to  isb  word  2. 


FORTRAN  interface  subroutines  for  analog  input  depend  on  asynchronous 
system  traps  t-o  set  their  status.  Thus,  If  the  trap  mechanism  is 
disabled,  proper  status  c.innot  be  set. 


Table  15-4 
Contents  of  First  Word  of  isb 


Contents 

Meaning 

isb(l)  =  0 
isb(l)  =  1 
isb(l)  =  3 

3  <  isb(l)  <  300 
Isb(l)  >  300 

Operation  pending;   I/O  In  progress 

Successful  completion 

Interface  subroutine  unable  to  generate 
QIO   directive   or   number   of   points 
requested  is  zero 

QIO  directive  rejected  and  actual  error 
code  =  -(isb(l)  -  3) 

Driver   rejected   request   and    actual 
error  code  =  -(Isb(l)  -  300) 
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For  direct  access  calls  (indicated  in  Table  15-5  below),  errors  are 
detected  and  returned  by  the  FORTRAN  interface  subroutine  itself, 
rather  than  by  the  driver.  Although  the  use  of  a  2-word  status  block 
is  therefore  unnecessary,  these  errors  are  returned  in  standard  format 
to  retain  compatibility  with  functions  called  through  010  directives 
and  handled  by  other  drivers.  Errors  of  this  type  that  may  be 
returned  are: 


isb(l) 


i«b(l)  -  -»^321 


Number  of  points  requested  is 
0 

Invalid  UDCll  module 


15.5.3   FORTRAN  Subroutine  Summary 

Table  15-5  lists  the  FORTRAN  interface  subroutines  supported  for  the 
UDCll  under  RSX-llM.  (D)  indicates  a  direct  access  call,  and  the 
optional  logical  unit  number  for  such  a  call  may  be  specified  to 
retain  compatibility  with  RSX-llD;  but  this  specification  is  ignored 
by  RSX-llM. 

The  following  subsections  briefly  describe  the  function  and  format  of 
each  FORTRAN  subroutine  call.  Note  the  use  of  ASUDLN  to  specify  a 
default  logical  unit  number.  Also  consider  the  numbering  conventions 
described  in  15.7.2. 

The  following  FORTRAN  functions  do  not  perform  I/O  directly,  but 
facilitate  conversions  between  BCD  and  binary. 

Convert  four  BCD  digits  to  a  binary  number: 

IBIN  »  KBCD2B(IBCD) 
Convert  a  binary  number  to  four  BCD  digits: 

IBCD  -  KB2BCD(IBIN) 


Table  15-5 
FORTRAN  Interface  Subroutines  for  the  UDCll 


Subroutine 

Function 

AIRD/AIRDW 

Perform  input  of  analog   data   in   random 

sequence 

A I SO/A I SOW 

Read  a  series  of  sequential  analog   input 

channels 

AO/AOW 

Perform  analog  output  on  several  channels 

(D) 

ASUDLN 

Assign  a  LUN  to  the  UDCll 

CTDI 

Connect   a   circular   buffer   to   receive 

contact  interrupt  data 

(continued  on  next  page) 
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Table  l'j-5   (Cont.) 
FORTRAN  Interface  Subroutines  for  the  UDCll 


Subroutine 

Function 

CTTI 

Connect   a   circular   buffer   to   receive 
timer  Interrupt  data 

DFDI 

Disconnect   a    buffer    from    contact 
interrupts 

DPTI 

Disconnect  a  buffer  from  timer  interrupts 

DI/DIW 

Read   several   16-polnt   contact   sense 

fields  (D) 

DOL/DOLW 

Latch  or  unlatch  several  Ifi-polnt  fields 

DOM/DOMW 

Pulse  several  16-point  fields  (D) 

RCIPT 

Read   the   state   of   a   single   contact 
Interrupt  point  (D) 

RDCS 

Read  the  contents  of  a  contact   interrupt 
circular   buffer,   returning  data  on  only 
those  points  that  have  changed  state 

RDDI 

Read  the  contents  of  a  contact   interrupt 
circular  buffer,  one  point  for  each  call 

ROT  I 

Read  the  contents  of  a   timer   interrupt 
circular  buffer,  one  entry  for  each  call 

RDWD 

Read  the  contents  of  a  contact   interrupt 
circular   buffer,   returning   16  bits  of 
module    data    and     change-of-state 
Information 

RSTI 

Read  a  single  timer  :iodule  (U) 

SCTI 

Set  a  timer  modul.3  to  an  initial  'alue 

15.5.4   AIRD/^IRDW:  Performing  Input  of  Analog  Data  in  Random  Sequence 

The  ISA  standard  AIRD/AIRDW  FORTRAN  subroutines  input  analog   data   in 
random  sequence.   These  calls  are  issued  as  follows: 


CALL 


iAIRD   I 
AIRDW  J 


(Inm, Icont, idata,[lsb] ,lun) 


inm 


The  number  of  analog  input  channels. 
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icont 

An  Integer  array  containing  terminal  connection  data-channel 
number  ( r ight- just  1  fled  in  bits  0-11)  and  gain  (bits  12-15),  as 
shown  in  Table  15-3. 

idats 

An  Integer  array  to  receive  the  converted  values. 


lab 


A  ?-word   integer   array  to   which   the   subroutine   status   is 
ret;irned . 


lun 

The  logical  unit  number. 

NOTE 
lun  is  a  required  parameter. 

The  isb  array  has  the  standard  meaning  defined  in  Section  15.5.2.  If 
inm  »  0,  then  isb(l)  =  3.  The  contents  of  idata  are  undefined  if  an 
error  occurs. 


15.5.5  AISQ/AISQW:   Reading  Sequential  Analog  Input  Channels 

The  ISA  standard  AISO/AISQW   FORTRAN   subroutines   read   a   series   of 
sequential  analog  input  channels.   These  calls  are  issued  as  follows: 

(  AISQ   ) 
CALL  {  )    (inm, icont, idata, [isbl , lun) 

(  AISOW  » 

inm 

The  number  of  analog  input  channels. 


icont 


An  integer  array  containing  terminal  connection  data-channel 
number  ( right- justi f led  in  bits  0-11)  and  gain  (bits  12-15),  as 
shown  in  Table  15-3. 


idata 

An  integer  array  to  receive  the  converted  values. 
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A  2-word   integer   arrny  to   which   the   subroutine   status   is 
returned . 


lun 


The  logical  unit  number. 


NOTE 
lun  ^s  a  required  parameter. 

For  sequential  analog  input,  channel  number  is  computed  in  steps  of 
one,  beginning  with  the  value  specified  in  the  first  element  of  icont. 
The  channel  number  field  is  ignored  in  all  other  elements  of  the 
array. 

The  gain  used  for  each  conversion  is  taken  from  the  respective  element 
in  icont.  Thus,  even  though  the  channel  number  is  ignored  in  all  but 
the  first  element  of  icont,  the  gain  must  be  specified  for  each 
conversion  to  be  performed. 

The  isb  array  has  the  standard  meaning  <iefined  in  Section  15.5.2.  If 
inm  =  ",  then  Isb(l)  =  3.  The  contents  of  idata  are  undefined  if  an 
error  occurs. 


15.5.6  AO/AOW:  Performing  Analog  Output 

The  ISA  standard  AO/AOW  FORTRAN  subroutines  initiate  analog  output   on 
several  channels.   These  calls  are  issued  as  follows: 

AO 
CALL  ^       ]      ( inm, icont, idata ,[ isbl ,[ lunl ) 
AOW 

inm 

The  number  of  analog  output  channels. 

icont 

An  integer  array  containing  the  channel  numbers. 

idata 

An  integer  array  containing  the  output  voltage  settings,   in   the 
range  0-1023. 
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A  2-word   integer  array  to  which   the  subroutine  status   is 
returned. 


lun 

The  loqical  unit  number  (ignored  if  present). 

The  isb  array  has  the  standard  meaning  defined  in  Section  15.5.2, 


15.5.7   ASUDLN:  Assigning  a  LUN  to  the  UDCll 

The  ASUDLN  FORTRAN  subroutine  assigns  the  specified  LUN  to  the 
specified  unit  and  defines  it  as  the  default  logical  unit  number  to  be 
used  whenever  a  LUN  specification  is  omitted  from  a  UDCll  subroutine 
call.   It  is  issued  as  follows: 

CALL  ASUDLN  (lun, f isw] , f i ^n] ) 


lun 


isw 


iun 


The  logical  unit  number  to  be  assigned  to  the  specified  unit,  and 
defined  as  the  default. 


An  integer  variable  to  which  the  result  of  the  ASSIGN  LUN  system 
directive  is  returned. 


An  integer  defining  the  UDCll   unit   number.    If   no   number   is 
specified,  0  is  assumed. 


15.5.8  CTDI:  Connecting  to  Contact  Interrupts 

The  CTDI  FORTRAN  subroutine  connects  a  task  to  contact  Interrupts  and 
specifies  a  circular  buffer  to  receive  contact  interrupt  data.  The 
length  of  this  buffer  can  be  computed  by  considering  the  following: 

•  Rate  at  which  contact  module  interrupts  occur 

•  Number  of  modules  that  can  interrupt  simultaneously 

•  Rate  at  which  the  circular  buffer  is  emptied 
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Th«  UDCll  driver  generates  a  S-word  entry  for  each  contact  Interrupt 
and  the  interface  subroutine  Itself  requires  10  words  of  additional 
storage.  Thus  the  isi  parameter,  described  below,  can  be  computed  as 
fol lows: 

isz  -  (10  +  5  •  n) 

where  n  is  the  number  of  entries  in  the  buffer  an(^  isz  is  expressed  in 
words. 

The  call  is  issued  as  follows: 

CALL  CTDI  (Ibuf ,isz,iev, fisbl , f lunl ) 

ibuf 

An  integer  array  that  is  to  receive  contact  interrupt  data. 


isz 


lev 


The  length  of  the  array  in  words,  with  a  minimum  size  of  15. 


The  trigger  event  flag  number.   The  specified  event  flag   is   set 
whenever  the  driver  inserts  an  entry  in  the  data  buffer. 


isb 

A   2-word   integer   array   to   which   the   subroutine   status   is 
returned . 

lun 

The  logical  unit  number. 
The  isb  array  has  the  standard  meaning  defined  in  Section  15.5.2. 

15.5.9  CTTI:  Connecting  to  Timer  Interrupts 

The  CTTI  FORTRAN  subroutine  connects  a  task  to  timer  interrupts  and 
specifies  a  circular  buffer  to  receive  timer  interrupt  data.  The 
length  of  this  buffer  can  be  computed  by  considering  the  following: 

•  Rate  at  which  timer  module  interrupts  occur 

•  Number  of  modules  that  can  interrupt  simultaneously 

•  Rate  at  which  the  circular  buffer  is  emptied 
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Th*  UDCll  driver  generates  a  4-word  entry  for  each  timer  interrupt  and 
the  interface  subroutine  itself  requires  8  words  of  additional 
storage.  Thus  the  isz  parameter,  described  below,  can  be  computed  as 
follows: 

isz  -  (R  ♦  4  •  n) 

where  n  is  the  number  of  entries  in  the  buffer  and  isz  is  expressed  in 
words. 

When  a  timer  module  interrupt  occurs,  the  driver  resets  the  count  to 
an  initial  value,  normally  that  specified  in  iv.  The  initial  value 
for  a  specific  module  can  be  modified  by  calling  the  SCTI  subroutine 
(see  Section  15.5.19). 

The  call  is  issued  as  followst 

CALL  CTTI  (ibuf ,isz,iev,iv, f isb) , f lun) ) 

ibuf 

An  integer  array  that  is  to  receive  timer  interrupt  data. 


isz 


iev 


iv 


isb 


The  length  of  the  array  in  words,  with  a  minimum  size  of  12. 


A  trigger  event  flag  number.   The  specified   event   flag   Is   set 
whenever  the  driver  inserts  an  entry  in  the  data  buffer. 


An  integer  array  that  contains  the  initial  timer  module  values, 
with  one  entry  for  each  timer  module,  where  entry  n  corresponds 
to  timer  module  number  n-1. 


A   2-word   integer   array   to   which   the   subroutine   status   is 
returned . 


lun 

The  logical  unit  number. 
The  isb  array  has  the  standard  meaning  defined  in  Section  15.5.2. 

15.5.10   DFDI:  Disconnecting  from  Contact  Interrupts 

The   DFDI   FORTRAN   subroutine   disconnects   a    task    from    contact 
interrupts.   It  is  issued  as  follows: 

CALL  DFDI  ( [isbl  , [lun]  ) 
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lab 

A   2-word   ln»-.«ger   array   to   which   the   subroutine   status   is 
returned . 

lun 

The  logical  unit  number. 
The  Isb  array  has  the  standard  meaning  defined  in  Section  15.5.2. 

15.5.11  DFTI:  Disconnecting  from  Timer  Interrupts 

The  DFTI  FORTRAN  subroutine  disconnects  a  task  from  timer   Interrupts. 
It  is  issued  as  follows: 

CALL  DFTI  ([isb] , [lun] ) 

isb 

A   2-word   integer   array   to   which   the   subroutine   status   is 
returned . 

lun 

The  logical  unit  number. 
The  Isb  array  has  the  standard  meaning  defined  in  Section  15.5.2. 

15.5.12  DI/DIW:  Reading  Several  Contact  Sense  Fields 

The  ISA  standard  DI/DIW  FORTRAN  subroutines   read   several   16-point 
contact  sense  fields.   These  calls  are  issued  as  follows: 

i     DI    I 
CALL  <       >   (inm,icont,idata,isb, [lun] ) 
(  DIW   ' 

inm 

The  number  of  fields  to  be  read. 


Icont 


An  integer  array  containing  the   initial   point   number  of   each 
field  to  be  read. 


idata 


An  integer  array  that  is  to  receive  the  input  data,   16  bits  of 
contact  data  for  each  field  read. 
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A   2-word   integer   array   to   which   the   subroutine   status   is 
returned . 


lun 

The  logical  unit  number  (ignored  if  present). 
The  isb  array  has  the  standard  meaning  defined  in  Section  15.5.2. 

15.5.13   DOL/DOLW:  Latching  or  Unlatching  Several  fields 

The  ISA  standard  DOL/DOLW  FORTRAN  subroutines  latch  or  unlatch  one  or 
more  Ifi-point  fields.   These  calls  are  issued  as  follows: 


CALL  <       >   (<nm,lcont, idata,lmsk, ( isb] , [lun] ) 


Inm 

The  number  of  fields  to  be  latched  or  unlatched, 


icont 


An  integer  array  containing  the   initial   point   number   of   each 
16-point  field. 


idata 


An  integer  array  that  specifies  the  points  to  be  latched  or 
unlatched;  bit  n  of  idata  corresponds  to  point  nun.oer  icont  +  n; 
if  the  corresponding  bit  in  imsk  is  set,  tho  bit  Is  changed;  a 
bit  value  of  1  indicates  latching,  and  0  unlatching;  each  entry 
in  the  array  specifies  a  string  of  16  points. 


imsK 


isb 


An  integer  array  in  which  bits  are  set  to  Indicate  points  whose 
states  are  to  be  changed  in  the  corresponding  idata  bits;  each 
entry  In  the  array  specifies  a  Ifi-bit  mask  word. 


A   2-word   integer   array   to   which   the   subroutine   status   Is 
returned . 


lun 

The  logical  unit  number. 
The  isb  array  has  the  standard  meaning  defined  In  Section  15.5.2. 
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15.5.14  DOM/DOMW:  Pulalnq  Several  Fields 

The  ISA  standard  DOM/DOMW  FORTRAN  subroutines  pulse  several  1^-bit 
fields  (1-shoc  digital  output,  points).  These  calls  are  issued  as 
fol lows: 

1  DOM   I 

CALL  \  \       (inin,icont,idata,  r  idx)  ,  f  isb)  ,  f  lunl  ) 

Ina 

The  number  of  fields  to  be  pulsed. 


icont 


An  integer  array  containing  the   l'>ltlal   point   number   of   each 
Ifi-point  field. 


idata 


idx 


isb 


An  integer  array  which  specifies  the  points  to  be  pulsed;   bit   n 
of  idata  corresponds  to  point  number  icont  ♦  n. 


A  dummy  argument  retained  for  compatibility  with  existing 
Instrument  Society  of  America  standard  FORTRAN  process  control 
cal Is. 


A   2-word   integer   array   ^o   which   the   subroutine   status   is 
returned . 


lun 

The  logical  unit  number  (ignored  if  present). 
The  isb  array  has  the  standard  meaning  defined  in  Section  15.5.3. 

15.5.15   RCIPT:  Reading  a  Contact  Interrupt  Point 

The  RCIPT  FORTRAN  subroutine  reads   the   state   of   a   single   contact 
interrupt  point.   It  is  issued  as  follows: 

CALL  RCIPT  (ipt,isb, riunl ) 


Ipt 


The  number  of  the  point  to  be  read;  points  are  numbered 
sequentially  from  0,  the  first  point  on  the  first  contact 
interrupt  module. 
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Isb 


lun 


A   2-wor(1   integer   array   to   which   the  subroutine   status   is 
returned . 


The  logical  unit  number  (ignored  if  present). 


The  isb  array  has  the  same  basic  meaning  defined  in  Section  15.5.2. 
However,  Isb  word  2  is  set  to  one  of  the  following  values, 
representing  the  state  of  the  point: 


Setting 

.FALSE.   (0) 
.TRUE.   (-1) 


Meaning 
Point  is  open 
Point  Is  closed 


NOTE 

To  increase  throughput,  the  subroutines 
RDCS,  RDDI,  RDTI,  and  RDWD  described  in 
the  following  four  sections  do  not  issue 
the  clear  Event  Flag  directive  until  a 
buffer-empty  condition  is  detected.  The 
calling  task,  therefore,  must  avoid 
Issuing  a  Walt-For  directive  until  a 
buffer-empty  Is  reported. 


15.5. Ifi  RDCS:  Reading  Contact  Interrupt  Change-of-State  Data  from  a 
Circular  Buffer 

The  RDCS  FORTRAN  subroutine  reads  contact  interrupt  data  from  a 
circular  buffer  that  was  specified  In  a  CTDI  call  (see  Section 
15.5.8).  It  does  no  actual  input  or  output,  but  rather  performs  a 
point-by-poInt  scan  of  an  interrupt  e;  '.ry  In  the  buffer,  returning  the 
state  of  each  point  that  has  changed  state  as  a  logical  value.  The 
trigger  event  flag  that  was  specified  In  the  CTDI  call  Is  cleared  when 
the  "buffer  empty"  condition  Is  detected. 


On  the  Initial  call  to  RDCS,   the   module   num 
change-of -state   word   of   the   next  interrupt 
circular  buffer  and  stored  for  subsequent  refe 
then   searches  the  entry  change-of-state  word 
encountered.   The  point  number  is  computed  and 
along   with   the   state   of   the  point.   Scann 
changed  state   resumes   on   the   next   call; 
bypassed.    The   next   entry  Is  automatically 
received  all  change-of-stato  information  from 
valid   entry   Is  not  found,  Ipt  Is  set  negativ 
is  either  assigned  a  value  of  0  or  an  overrun 
UDCll   driver.    If   ict   Is   0,  no  further  en 
value  Indicates  that  the  driver   received   mor 
stored   In   the   buffer,  and  ict  represents  th 
were  discarded. 


ber,  module 
entry  are  r 
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The  HDCS   call  is  Issued  as  follows: 
CALL  ROCS  (ipt,ival,[ict1 ) 


Ift 


Ival 


A  variable  to  which  the  digital  input  point  number   is   returned; 
it  may  be  set  as  follows: 

e   ipt   0  if  no  valid  entry  is  found  (that  is,  no  interrupt   data 

currently  in  buffer,   or   overrun  detected).    One  of   the 

following  values   is   returned   to   indicate   the   condition 
detected : 

-1   -  Buffer  empty 

-2   ■   Overrun  detected 

e   ipt  ■>  0  if  the  value  indicated  Is  a   point   number   that   has 
changed  state;   the  state  is  returned  to  Ival. 


A  variable  to  which  the  state  of  the  point  is  returned;    it  may 
be  set  as  follows: 

e   .FALSE.   (0)  if  the  point  is  open 

e   .TRUE.   (-1)  if  the  point  is  closed 


An  integer  variable  for  receiving  the  overrun  count.  A  nonzero 
positive  count  indicates  that  the  driver  was  unable  to  store  the 
number  of  interrupts  indicated. 


15.5.17   RDDI:  Reading  Contact  Interrupt  Data  from  a  Circular  Buffer 

The  RDDI  FORTRAN  subroutine  reads  contact  interrupt  data  from  a 
circular  buffer  that  was  specified  in  a  CTDI  call  (see  Section 
15.5.8).  It  does  no  actual  input  or  output,  but  rather  performs  a 
point-by-point  scan  of  an  interrupt  entry  in  the  buffer,  returning  the 
state  of  each  point  as  a  logical  value.  The  trigger  event  flag  that 
was  specified  in  the  CTDI  call  is  also  cleared. 

On  the  initial  call  to  RDDI,  the  module  number  and  data  of  the  next 
interrupt  entry  are  read  from  the  circular  buffer  and  stored  for 
subsequent  reference.  The  subroutine  then  sets  the  current  data  bit 
number  n  to  0,  examines  the  state  of  data  bit  n,  and  converts  bit  n  to 
a  point  number  by  the  following  formula: 

ipt  =  module  number  *  Ifi  +  n 


let 
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On  each  subsequent  call,  n  is  incramantad  by  one  and  than  data  bit  n 
is  examined  in  the  stored  module  data.  When  n  reaches  Ifi,  it  is  reset 
to  0  and  an  attempt  is  made  to  read  the  next  interrupt  en^ry  from  the 
circular  buffer.  If  a  valid  entry  is  not  found,  1 pt  is  set  negative 
and  ict  (if  specified)  is  either  assigned  a  value  of  0  or  an  overrun 
count  maintained  by  the  UDCll  driver.  If  ict  is  0,  no  further  entries 
remain.  A  nonzero  value  indicates  that  the  driver  received  more  data 
than  could  be  stored  in  the  buffer,  and  let  represents  the  number  of 
entries  that  were  discarded. 

The  RDDI  call  is  Issued  as  follows: 

CALL  RDDI  (ipt,ival, f ict] ) 


Ipt 


ival 


A  variable  to  which  the  digital  input  point  number   is   returned; 
it  may  be  set  as  follows: 

•  ipt  0  If  no  valid  entry  is  found  (that  is,  no  Interrupt  data 
currently  in  buffer,  or  buffer  empty).  One  of  the  following 
values  is  returned  to  indicate  the  condition  detected: 

-l«Buffer  empty 
-2"0verrun  detected 

a  Ipt  ">  0  If  the  value  Indicated  is  a  point  number;  the  state 
Is  returned  to  Ival 


A  variable  to  which  the  state  of  the  point  is  returned;    it   may 
be  set  as  follows: 

•  .FALSE.  (0)  if  the  point  is  open 

•  .TRUE.  (-1)  if  the  point  is  closed 


A  variable  to  which  che  overrun  count  may  be  returned;  a  nonzero 
positive  count  Indicates  that  the  driver  was  unable  to  store  the 
number  of  entries  indicated. 


15.5.18   RDTI:  Reading  Timer  Interrupt  Data  from  a  Circular  Buffer 

The  RDTI  FORTRAN  subroutine  reads  timer  interrupt  data  from  a  circular 
buffer  that  was  specified  in  a  CTTI  call  (see  Section  15.5.9).  It 
does  no  actual  input  or  output,  but  rather  performs  a  scan  of  each 
entry  in  the  buffer,  returning  the  timer  value  for  each  call.  The 
trigger  event  flag  that  was  specified  in  the  CTTI  call  is  also 
cleared . 

When  a  timer  module  interrupt  occurs,  the  UDCll  driver  resets  the 
count  to  an  initial  value,  usually  that  specified  in  the  iv  array  on 
the  CTTI  call.  The  initial  value  can  be  modified  for  a  specific 
module  by  calling  the  subroutine  SCTI  (see  Section  15.5.19). 


ict 
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The  RDTI  call  is  issued  as  follows: 
CALL  RDTI  (imod.itm, [ivrn] ) 


inod 


ita 


A  variable  to  which  the  module  number  is  returned;   it  may  be  set 
AS  follows: 

e  Imod  0  if  no  valid  entry  Is  found  (that  Is,  no  interrupt  data 
currently  in  buffer,  or  buffer  empty).  One  of  the  following 
values  is  returned  to  indicate  the  condition  detected: 

-l»Buffer  empty 
-2"0verrun  detected 

e  imod  >  0  if  the  entry  is  valid,  indicating  a  module  number; 
the  value  of  the  timer  module  Is  returned  in  itm 


A  variable  to  which  the  timer  value  is  returned. 


ivrn 


A  variable  to  which  the  overrun  count  may  be  returned;  a  nonzero 
positive  count  indicates  that  the  driver  was  unable  to  store  the 
number  of  values  indicated. 


15.5.19  RDWD:   Reading  a  Full  Word  of  Contact  Interrupt  Data  from  the 
Circular  Buffer 

The  RDWD  FORTRAN  subroutine  reads  a  full  word  of  contact  Interriipt  and 
change-of-state  data  from  the  circular  buffer  that  was  specified  in  a 
CTDI  call  (see  Section  15.5.8).  It  does  no  actual  Input  or  output, 
but  rather  performs  a  scan  of  each  entry,  returning  the  state  of  a 
module  and,  optionally,  the  change-of-state  data  for  each  call.  The 
trigger  event  flag  specified  in  the  call  to  CTDI  is  cleared. 

The  call  to  RDWD  is  issued  as  follows: 

CALL  RDWD  ( imod , i St , r ivrn] , f icos] ) 


imod 


A  variable  to  which  the  module  number  is  returned;   it  may  be  set 
as  follows: 

•  imod  0  if  no  valid  entry  is  found  (that  is,  no  interrupt  data 
currently  in  buffer  or  overrun  detected).  One  of  the 
following  values  is  returned  to  indicate  the  condition 
detected ; 

-l=Buffer  empty 
-2=0verrun  detected 
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1st 

A  variable  to  which  the  module  data  is  returned. 

Ivrn 

A  variable  to  which  the  overrun  count  may  be  returned;  a 
nonzero,  positive  count  indicates  that  the  driver  was  unable  ta 
store  the  number  of  entries  indicated. 


icos 


A  variable  to  which  the  change-of-state  data  Is  returned.  One 
bit  is  set  for  each  point  that  has  changed  state  in  the  direction 
indicated  by  the  "point  open"  (POP)  or  "point  closed"  (PCL) 
jumpers  on  the  module. 


15.5.20  RSTI:  Reading  a  Timer  Module 

The  RSTI  FORTRAN  subroutine  reads  a  single  timer  module.   It  is  issued 
as  follows: 

CALL  RSTI  (imod,lsb, [lun] ) 

imod 

The  module  number  of  the  timer  to  be  read. 

» 

isb 

A   2-word   integer   array   to  which   the   subroutine   status   is 
returned . 

lun 

The  logical  unit  number  (ignored  if  present). 
The  isb  array  has  the  standard  meaning  defined  in  Section  15.5.2. 

15.5.21  SCTI:  Initializing  a  Timer  Module 

The  SCTI  FORTRAN  subroutine  sets  a  timer  module  to  an   initial   value. 
It  is  issued  as  follows: 

CALL  SCTI  (imod, ival, [isb]  , [lun]  ) 

imod 

The  module  number  of  the  timar  to  be  set. 
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Ival 


lab 


The  Initial  timer  value. 


A   2-word   integer   array   to  which   the   subroutine   status   Is 
returned . 


lun 

The  logical  unit  number. 

The  Isb  array  has  the  standard  meaning  defined  in  Section  15.5.2. 

Calls  to  initialize  a  counter  are  valid  only  if  the  issuing   task   has 
connected  a  buffer  for  receiving  counter  Interrupts  by  a  call  to  CTTI. 


15.6   STATUS  RETURNS 

Table  15-'5  lists  the  error  and  status  conditions  that  are  returned   by 
the  UDCll  driver  described  in  this  chapter: 


Table  15-6 
UDCll  Status  Returns 


Code 

Reason 

IS. sue 

Sucessful  completion 

The  operation  specified   in   the   010  directive   was 

completed   successfully.    The  second  word  of  the  I/O 

status  block  can  be  examined  to  determine  the   number 

of  samples  completed  or  converted. 

IS.PND 

I/O  request  pending 

The  operatlori  specified  in  the  QIO   directive  has   not 

yet   been   executed.    The  I/O  status  block  is  filled 

with  Os. 

IE. ABO 

Operation  aborted 

The  specified  I/O  operation  was  canceled  with   lO.KIL 

while  still  in  the  I/O  queue. 

IE. BAD 

Bad  parameter 

An  illegal  specification  was  supplied  for  one  or  more 

of   the  device-dependent  QIO  parameters  (words  6-11). 

For  the  UDCll,  this  code  indicates  an  illegal  channel 

number  or  gain  code  for  the  ADUOl. 

(continued  on  next  page) 
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Table  15-6   (Cont.) 
UDCll  Status  Returns 


Code 


IE, 'YT 


IE. CON 


Reason 


Byte-aligned  buffer  specified 

Byte  alignment  was  specified  for  a  buffer  but  only 
word  alignment  is  legal  for  the  UD'"12.  Alternately, 
the  length  of  a  buffer  was  not  an  even  number  of 
bytes. 

Connect  error 


lE.DNR 


lE.IEF 


The  task  attempted  to  connect  to  contact  or  timer 
interrupts,  but  ••he  interrupt  was  already  connected 
to  another  task.  Only  one  task  can  be  connected  to  a 
timer  or  contact  interrupt.  Alternately  a  task  v'lich 
was  not  connected  attempted  to  disconnect  irom 
contact  or  timer  interrupts. 


Device  not  ready 

The   physical   device   unit   specifieu 
directive   was   not   ready  to  perform  t 
operation.   For  the  ADUOl,  this  code  is 
an  interrupt  time  out  occurred  or  the 


in   the    QIO 
desired  I/O 
reLuiiisd   if 
power  failed. 


Invalid  event  flag  number 


An  invalid  trigger  event  flag  number  was  specified  in 
a  connect  function. 


IE. IPC 


IE. MOD 


Illegal  function 


A  function  code  was  included  in  an  I/O   request   that 
is   illegal  for  the  UDCll,  or  a  request  to  initialize 

not 
The 


a  counter  (lO.ITI)  was  issued  by  a 
connected  to  receive  counter 
function  may  also  refer  to  a  UDCll 
not  specified  at  system  generation, 


task  that  was 

interrupts . 
feature  which 


was 


Invalid  UDCll  module 


On  latching  output,  the  user  specified  a  starting 
point  number  that  was  not  legal  (defined  at  system 
generation)  or  was  not  evenly  divisible  by  16. 

lE.OFL       Device  off  line 

The  physical  device   unit   associated   with   the  tUN 

specified  in  the  QIO  directive  was  not  on  line.  When 

the  system  was  booted,  a  device  check  indicated  that 

this  physical  device  unit  was  not  in  the 
configuration. 


(continued  on  next  page) 


• 
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Table  15-6   (Cont.) 
UDCll  .Status  Returns 


Code 


lE.PRI 


lE.SPC 


Reason 


Privilege  violation 

The  task  which  Issued  the  request  was  not  privileged 
to  execute  that  request.  For  the  UDCll,  this  code 
indicates  that  a  checkpointable  'cask  attempted  to 
connect  to  timer  or  contact  interrupts. 

Illegal  address  space 

The  specified  control,  data,  or  interrupt  buffer  was 
partially  or  totally  outside  the  address  space  of  the 
issuing  task.  Alternately,  the  interrupt  buffer  was 
too  small  for  a  single  data  entry  (six  words  for 
timer  interrupts  and  seven  ords  for  contact 
interrupts),  or  a  byte  count  of  0  was  specified. 


FORTRAN  interface  values 
Section  15. 6.  1 . 


for  these  status   returns   are   presented   in 


15.fi. 1   FORTRAN  Interface  Values 

The  values  listed  in  Table  15-7  are   returned   in   FORTRAN   subroutine 
cal Is. 


Table  15-7 
FORTRAN  Interface  Values 


Status  Return 

FORTRAN  Value 

IS. sue 

+01 

IS.PND 

+  00 

IE. ABO 

+  315 

lE.ADP 

+  101 

IE. BAD 

+  301 

IE. BYT 

+  319 

lE.DAO 

+  313 

lE.DNR 

+  303 

lE.IEF 

+  100 

lE.IFC 

+  302 

lE.ILU 

+  99 

IE. MOD 

+  321 

lE.ONP 

+  305 

I  E . PR  I 

+  316 

lE.RSU 

+  317 

lE.SDP 

+  102 

lE.SPC 

+  306 

lE.ULN 

+  08 

lE.UPN 

+  04 
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15.7   PROGRAMMING  HINTS 

This  section  contains  Information  on  important  programming 
considerations  relevant  to  users  of  ths  UDCll  driver  described  in  this 
chapter. 


15.7.1  Numbering  Conventions 

Numbering  Is  relative.  Module  numbers  start  at  0,  beginning  with  the 
first  module  of  a  given  type. 

Channel  numbers  also  start  at  0,  with  channel  0  as  the  first  channel 
on  the  first  module  of  a  given  type.  For  the  ADUOl,  channel  8  Is  the 
first  channel  on  the  second  analog  output  module. 

Each  lAD-IA  module   installed   in   an   ICSll   subsystem   occupies  120 

channels   (regardless  of   the   number  of  multiplexers  installed).  In 

this  case,  channel  120  Is  the  first  channel  on  the  second  lAD-IA  A/D 
converter . 

Point  numbers  start  at  0,  with  point  0  as  the  first  point  on  the  first 
module  of  a  given  type.  For  instance,  point  20(8)  is  the  first  point 
of  the  second  contact  sense  module  (that  is,  relative  module  number 
1). 


15.7.2   Processing  Circular  Buffer  Entries 

Circular  buffer  entries  should  be  processed  in  the  following  sequence. 

1.  Execute  a  WAITFOR  system  directive  using  the  trigger  event 
flag  specified  in  the  subroutine  called  to  connect  the 
circular  buffer  (CTTI  or  CTDI). 

2.  Repeatedly  call  the  appropriate  subroutine  to  road  the 
circular  buffer  until  all  entries  have  been  obtained  and  ipt 
indicates  that  the  buffer  is  empty  (-1). 

3.  Perform  any  other  processing  and  return  to  step  1. 
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LABORATORY  PERIPHERAL  SYSTEMS  DRIVERS 


16.1   INTRODUCTION 

The  LPSll  and  ARll  Laboratory  Peripheral  Systems  are  modular, 
real-time  subsystems  used  for  the  acquisition  and/or  output  of 
laboratory  analog  data.  (Laboratory  Peripheral  Systems  drivers  are 
not  supported  on  RSX-llM-PLUS  systems.)  Table  16-1  compares  the  LPSll 
with  the  ARll. 


Table  16-1 
Laboratory  Peripheral  Systems 


LPSll 

ARll 

Analoq-to-Digital  Conversion 
(with  Sample  and  Hold 
Circuitry) 

12  bits  of  precision 
16-channel  multiplexer 
with  gain  ranging 

Maximum  of  64  channels 
without  gain  ranging 

10  bits  of  precision 
16-channel  multiplexer 
without  gain  ranging 

Programmable  Real-Time  Clock 

Yes 

Yes 

Digltal-to-Analog  Output 

12  bits  of  precision 
10  channels  (includ- 
ing display) 

10  bits  of  precision 
2  channels  (including 
display) 

Display  Control 

4096  by  4096  dot  matrix 

1024  by  1024  dot  matrix 

Digital  I/O  Option 

16  digital  points 
and  programmable 
relays 

16  digital  points 
(available  with 
DRll-K  option) 

At  system  generation,  the  user  can  specify  the  following: 

•  The  number  of  A/D  channels 

•  The  presence  or  absence  of  the  gain-ranging  option  (LPSAM-SG) 
(LPSll  only)  and  the  polarity  of  each  channel  (uni-  or 
b  1  po 1  a  r ) 

•  The  presence  or  absence  of  the  external  D/A  option  (LPSVC  and 
LPSDA) ,  and  if  present,  the  number  of  D/A  channels 

•  The  clock  preset  value 
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1ft.  1.1  ARll  Laboratory  Peripheral  System 


ARll  is  a  l-module   real-time  analog  subsystem  that  interfaces 

PDP-11  family  of  computers  by  a  "hex"  small  peripheral  controller 

is  a  subset  of  the  LPSll  and,  as   such,   enjoys   the 

The  ARll  includes  a  Ifi-channel,  10-bit 

i.wld,   a   programmable   real-time   clock 

and  a  display  control  with  two  10-bit  D/A 


The 

the 

slot.   The  system 

same   degree   of   flexibility.   — 

A/D  converter  with  sample-and-hold , 

with  one   external   input, 

converters. 


to 


16.1.2  LPSll  Laboratory  Peripheral  System 


The  LPSll  1 
flexibility 
research,  a 
monitoring , 
technical  e 
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13-bit  A/D 
triggers , 
16-bit  digi 
added  to  th 
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interface  with 
r,  a  programma 
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option.   Up  to 
package. 


modular  , 
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ion,  data 
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ubsystem, 

external 
ble  real- 
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real -time 
at  ions ,  in 
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testing  , 
built  In 
Instrumen 
time  clock 
12-bit  D/A 
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subsystem  with  the 
eluding  biomedical 
n   and   reduction, 

engineering,  and 
a  compact  size  and 
tatlon.  Includes  a 
,  with  two  Schmitt 

converters,  and  a 
Ion  types  may  be 


16.2   GET  LUN  INFORMATION  MACRO 


If  a  GET  LUN  INFORMATION  system  directive  Is  issued  for  a  LUN 
associated  with  a  Laboratory  Peripheral  System,  word  2  (the  first 
characteristics  word)  contains  all  Os  words  3  and  A  are  undefined,  and 
word  5  contains  a  16-bit  buffer  preset  value  that  controls  the  rate  of 
the  real-time  clock  interrupts,  as  explained  in  Section  16.6.1. 


16.3   QIO  MACRO 

This  section  summarizes  standard  and  device-specific  QIO  functions  for 
the  Laboratory  Peripheral  System  drivers. 


16.3.1   Standard  QIO  Function 

Table  16-2  lists  the  standard  function  of  the  QIC  macro  that  is   valid 
for  the  Laboratory  Peripheral  Systems. 


Table  16-2 
Standard  QIC  Function  for 
Laboratory  Peripheral  Systems 


Format 

Function 

QIO$C  lO.KIL,... 

Cancel  I/O  requests 

lO.KIL  cancels  all  queued  and  in-progress  I/O  requests, 
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16.3.2   D«vic«-Sp«cif ic  QIO  Functions  (Immediate) 


Except  for  lO.STP  (see  Section  l';.3.4),  all  devlce-gpecl  f  Ic  functions 
of  the  010  macro  that  are  valid  for  the  Laboratory  Peripheral  Systems 
are  either  Immediate  or  synchronous.  Each  Immediate  function  performs 
a  complete  operation,  whereas  each  synchronous  function  simply 
initiates  an  operation  synchronized  to  the  real-time  clock.  Table 
16-3  lists  the  immediate  functions. 


Table  16-1 
Device-Specific  010  Functions  for  the 
Laboratory  Peripheral  Systems  (Immediate) 


Format 

Function 

QIOSC  10. LED, . . . ,<int,num> 

OIOSC  lO.REL, . . . ,<rel ,pol> 
QIOSC  lO.SDI, .  .  .  ,<ma.sk> 
OIOSC  10. SDO, . . . ,<mask ,data> 

DISPLAY  number  In  LED  lights 
(LPSll  only) 

LATCH  output  relay  (LPSll  only) 

READ  digital  input  register 

WRITE  digital  output  register 

int 


num 


rel 


The  l*>-bit  signed  binary  integer  to  display. 


The  LED  digit  number  where  the  decimal  point  is  to  be  placed, 


The  relay  number  (0  or  1) 


pol 


The  polarity  (0  for  open,  nonzero  for  closed) 


mask 


data 


The  mask  word. 


The  data  word, 


The  following  subsections  describe  the  functions  listed  above. 
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1«.3.2.1  lO.LKD  -  This  LPRll-only  function  displays  a  16-blt  signed 
binary  Integer  In  the  light-emitting  diode  (LED)  lights.  The  '^umber 
Is  displayed  with  a  leading  blank  (positive  number)  or  minus  sign 
(negative  number),  followed  by  five  non-zero-suppressed  decimal  digits 
that  represent  the  magnitude  of  the  number.  LED  digits  are  numbered 
from  right  to  left,  starting  at  1. 

The  number  may  be  displayed  with  or  without  a  decimal  point.  If  the 
parameter  num  Is  a  number  from  1  to  5,  then  the  corresponding  LED 
digit  Is  displayed  with  a  decimal  point  to  the  right  of  the  digit.  If 
the  LED  digit  number  is  not  a  number  from  1  to  5,  then  no  decimal 
point  Is  displayed. 


16. 3.?. 2  lO.REL  -  This  LPSll-only  function  opens  or  closes  the 
programmable  relays  In  the  digital  I/O  status  register.  Approximately 
300  milliseconds  are  required  to  open  or  close  a  relay.  The  driver 
imposes  no  delays  when  executing  this  function.  Thus  it  is  the 
responsibility  of  the  user  to  Insure  that  adequate  time  has  elapsed 
between  the  opening  and  closing  of  a  relay. 


lfi.3.2.3  lO.SDI  -  This  function  reads  data  qualified  by  a  mask  word 
from  the  digital  input  register.  The  mask  word  contains  a  1  in  each 
bit  position  from  which  data  is  to  be  read.  All  o'-her  bits  are  zero 
filled  and  the  resulting  value  is  returned  in  the  second  I/O  status 
word . 

The  operation  performed  is: 

RETURN  VALUE=MASK. AND. INPUT  REGISTER 


16.3.2.4   lO.SDO  -  This  function  writes  dcita  qualified  by  a  mask  word 

into   the  ^^igital  output  register.   The  mask  word  contains  a  1  in  each 

bit  position  that  is  to  be  written.   The  data  word  specifies  the  data 
to  be  written  in  corresponding  bit  positions. 

The  operation  performed  is: 

NEW  REGISTER=<MASK.AND.DATA>.OR.<<.NOT.MASK>.AND.OLD  REGISTER> 


lfi.3.3   Device-Specific  QIO  Functions  (Synchronous) 

Tabl  :>  16-4  lists  the  synchronous,  device-specific  functions  of  the  QIO 
macro  that  are  valid  for  the  Laboratory  Peripheral  Systems. 


# 
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Table  16-4 
Device-Specific  QIO  ''unctions  for  the 
Laboratory  Peripheral  Systems  (Synchronous) 


Format 

Function 

QIO$C 

10. ADS, 

. . . ,<stadd ,size ,pnt, 
ticks, bufs,chna> 

INITIATE  A/D  sampling 

QIOSC 

10. HIS, 

. ..,<stadd,size,pnt, 
cickSjbuf s> 

INITIATE  histogram  sanpling 
(LPSll  only) 

QIO$C 

ir  MDA, 

. . . ,<stadd ,size ,pnt, 
ticks, bufs,chnd> 

INITIATE  D/A  output 

QIO$C 

lO.MDI, 

. . . ,<staad  .size  pnt , 
ticks, bufs,mask> 

INITIATE  cUgital  input 
sampl  .'ng 

QIO$C 

lO.MDO, 

...,<'  ♦•.add  ,size,pnt, 
ticks, bufs,mask> 

INITIATE  digital  output 

stadd 


size 


pnt 


The  starting  address  of  the  data   buffer   (must   be  on  a   word 
boundary) . 


The  data  buffer  size  in  bytes  (must   be  greater   than   0   and   a 
multiple  of  four  bytes). 


The  digital  point  numbers  (byte  0  -  starting   input/output   point 

number;    byte   1  -  input   point  number   to   stop  the  function). 

Points  are  numbered  from  0  to  15,  allowing  a  maximum  of  16  points 
to  be  specified. 


ticks 


bufs 


The  number  of  real-time   clock   ticks   between   samples   or   d.ita 
transfers,  as  appropriate. 


The  number  of  data  buffers  to  transfer. 
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chna 


The  an'>log-to-digital  conversion  specification.  Byte  0  contains 
the  starting  channel  number.  For  LPSll  this  must  be  In  the  range 
of  0-63;  for  ARll  the  range  Is  0-15.  If  the  LPSll  gain-ranging 
option  is  present,  the  channel  number  must  be  in  the  range  of 
0-15,  and  bits  4  and  5  specify  the  gain  code. 

Byte  1  contains  the  number  of  consecutive  analog-to-dlgital 
channels  to  sample.  For  LPSll  this  must  be  In  the  range  of  1-64; 
for  ARll  or  the  LPSll  with  gain-ranging,  the  .ange  is  1-16. 


chnd 


The  digital-to-analog  output  channel  specification.  Byte  0 
contains  the  starting  channel  number.  For  LPSll  this  must  be  in 
the  range  of  0-9;   for  the  ARll  the  range  is  0-1. 

Byte  1  containr.  the  number  of  consecutive  channels  to  be  output. 
For  LPSll  this  must  be  in  the  range  of  1-10;  for  ARll  the  range 
Is  1-2. 


mask 

The  mask  word. 
The  following  subsections  describe  the  functions  listed  above. 


16.3.3.1  10. ADS  -  This  function  reads  one  or  more  A/D  channels  at 
precisely  timed  intervals,  with  or  without  auto  gain-ranging.  If  two 
or  more  channels  are  specified,  all  are  sampled  at  approximately  the 
same  time,  once  per  interval. 

Sampling  may  be  started  when  the  request  is  dequeued  or  when  a 
specified  di-^^tal  input  point  is  set.  A  digital  output  point  may 
optionally  be  set  when  sampling  is  started.  Campling  may  be 
terminated  by  a  program  request  ,IO.STP  or  lO.KIL),  by  the  clearing  of 
a  digital  input  point,  or  by  the  collection  of  a  specified  number  of 
buffers  of  data. 

All  input  is  double  buffered  with  respect  to  the  user  task.  Bach  time 
a  half  buffer  of  data  has  been  collected,  the  user  task  is  notified 
(by  the  setting  of  an  event  flag)  that  data  is  available  to  be 
processed  while  the  driver  fills  the  other  half  of  the  buffer.  If  the 
user  task  does  not  respond  quickly  enough,  a  data  overrun  may  result. 
This  occurs  if  the  driver  attempts  to  put  another  data  item  in  the 
user  buffer  when  no  space  is  available. 

The  subfunctlon  modifier  bits  are  identical  to  those  described  in 
Section  16.3.3.2.  In  addition,  setting  bit  3  to  a  1  means  LPSll  auto 
gain-ranging  is  requested.  Bit  3  is  ignored  for  the  ARll.  If  bits  7 
and  6  are  both  set  to  1,  the  digital  input  point  and  digital  output 
point  number  are  assumed  to  be  the  same. 
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If  LPSll  auto  gain-ranging  is  used,  tha  LPSAM-SG  hardware  option  must 
be  present  and  specified  at  system  generation.  The  auto  gain-ranging 
algorithm  causes  a  channel  to  be  sampled  at  the  highest  gain  at  which 
saturation  does  not  occur.  If  the  gain-ranging  option  is  present  and 
auto  gain-ranging  is  not  specified  in  bit  3  of  the  subfunction  code, 
then  bits  4  and  5  of  the  starting  channel  number  specify  the  gain  at 
which  samples  are  to  be  converted.   Gain  codes  are  as  follows: 

Code  Gain 

00  1 

01  4 

10  16 

11  64 

Data  words  written  into  the  user  buffer  contain  the  converted  value  in 
bits  0-11  and  the  gain  code,  as  shown  below,  in  bits  12-15: 

Code  Gain 

0000  1 

0001  4 

0010  16 

0011  64 

If  the  LPSAM-SG  option  is  present,  then  each  channel  must  have  been 
defined  as  uni-  or  bipolar  at  system  generation.  In  addition,  if 
bandwidth  filtering  is  enabled  (and  so  indicated  at  system  generation 
time)  ,  a  software  delay  is  imposed  by  the  driver  when  the  multiplexer 
channel  is  changed.  This  delay  must  have  been  specified  at  SYSGEN. 
See  the  LPSll  Laboratory  Peripheral  System  User' s  Guide. 

The  ARll  always  returns  data  that  is  equivalent  to  an  LPSll  gain  of  1. 
Channel  polarity  must  always  be  specified  for  the  ARll  at  system 
generation,  since  this  operation  is  software  selectable  at  the  time 
sampling  is  initiated. 


16.3.3.2  10. HIS  -  This  LPSll-only  function  measures  the  elapsed  time 
between  a  series  of  event"?  by  means  of  Schmitt  trigger  1.  Each  time  a 
sample  is  to  be  taken,  a  counter  is  incremented  and  Schmitt  trigger  1 
is  tested.  If  it  has  fired,  then  the  counter  is  written  into  the  user 
buffer  and  reset  to  0.  Thus,  the  data  item  returned  to  the  user  is 
the  number  of  sample  intervals  between  Schmitt  trigger  firings. 

If  the  counter  overflows  before  Schmitt  trigger  1  fires,  then  a  0 
value  is  written  into  the  user  buffer.  Sampling  may  be  started  and 
stopped  as  described  in  Section  16.3.3.1.  All  input  is  double 
buffered  with  respect  to  the  user  task. 

The  subfunction  modifier  bits  appear  below.  A  setting  of  1  indicates 
the  action  listed  in  *.he  right-hand  column. 
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Bit  Meaning 

0-3  Unused 

4  Stop  on  number  of  buffers 

5  Stop  on  digital  input  point  clear 

il|i  Sot  digital  output  point  at  start  of  operation 

7  Start  on   digital    input   point   set    (a   0 

specification  means  start  immediately).  Points 
are  numbered  from  0  to  15,  allowing  a  maximum  of 
16  points  to  be  specified. 

-•'''''       ■■■■.'■  ,'.'  >)  ',  :' 

16.3.3.3  lO.MDA  -  This  function  writes  data  into  one  or  more  external 
D/A  converters  at  precisely  timed  intervals.  If  two  or  more  channels 
are  specified,  all  are  written  at  approximately  the  same  time,  once 
per  interval.  Output  may  be  started  or  stopped  as  described  in 
Section  16.3.3.1.  All  output  is  double  buffered  with  respect  to  the 
user  task. 

D/A  converters  0  ar.d  1  correspond  to  the  X  and  Y  registers  of  the 
display  control.  Note  that  there  are  no  specific  driver  functions  to 
set  the  display  status  register.  This  is  reserved  for  the  user.  D/A 
converters  2  through  9  correspond  to  the  LPSll,  LPSDA  external  D/A 
option. 

The  subfunction  modifier  bits  are  identical  to  those  described  in 
Section  16.3.3.2. 


16.3.3.4  lO.MDI  -  This  function  provides  ths  capability  to  read  data 
qualified  by  a  mask  word  from  the  digital  input  register  at  precisely 
timed  intervals.  Sampling  May  be  started  and  stopped  as  described  in 
Section  16.3.3.1.  All  input  is  double  buffered  with  respect  to  the 
user  task. 

The  mask  word  contains  a  1  in  each  bit  position  from  which  data  is  to 
be  read.   All  other  bits  are  0. 

The  subfunction  modifier  bits  are  identical  to  those  described  in 
Section  16.3.3.2. 


16.3.3.5  lO.MDO  -  This  function  writes  data  qualified  by  a  mask  word 
into  the  digital  output  register  at  precisely  timed  intervals.  Output 
may  be  started  and  stopped  as  described  in  Section  16.3.3.1.  All 
output  is  double  buffered  with  respect  to  the  user  task. 

The  subfunction  modifier  bits  are  identical  to  those  described  in 
Section  16.3.3.2. 
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16.3.4   Device-Specific  QIO  Function  (lO.STP) 

Table  16-5  lists  the  device-specific  function  of  the  QIO  macro,   which 
is  valid  for  the  Laboratory  Peripheral  Systems. 


Table  16-5 

Device-Specific  QIO  Function  for  the 

Laboratory  Peripheral  Systems  (lO.STP) 


Formal 

Function 

0IO$C  lO.STP,... ,<STADD> 

STOP  in-progress  request 

stadd 


The  buffer  address  of  the  function  to  stop  (must  be  the   same   as 
the  address  specified  in  the  initiating  request). 


16.3.4.1  lO.STP  -  lO.STP  stops  a  single,  in-progress  synchronous 
request.  It  is  unlike  lO.KIL  in  that  it  cancels  only  the  specified 
request,  whereas  lO.KIL  cancels  all  requests. 


16.4   FORTRAN  INTERFACE 

A  collection  of  FORTRAN-callable  subroutines  provide  FORTRAN  programs 
access  to  the  Laboratory  Peripheral  Systems.  These  routines  are 
described  in  this  section. 

Some  of  these  routines  may  be  called  from  FORTRAN  as  either 
subroutines  or  functions.  All  are  reentrant  and  may  be  placed  in  a 
resident  library. 


16.4.1   The  isb  Status  Array 

The  isb  (I/O  status  block)  parameter  is  a  2-word  integer  array  that 
contains  the  status  of  the  FORTRAN  call,  in  accordance  with  ISA 
convention.   This  array  serves  two  purposes: 

1.  It  is  the  2-word  I/O  status  block  to  which  the  driver  returns 
an  I/O  status  code  on  completion  of  an  I/O  operation. 

2.  The  first  word  of  the  isb  receives  a  status  code  from  the 
FORTRAN  interface  in  ISA-compatible  format,  with  the 
exception  of  the  I/O  pending  condition,  which  is  indicated  by 
a  status  of  0.  The  ISA  standard  code  for  this  condition  is 
+2. 

The  meaning  of  its  contents  vaiies,  depending  on  the  FORTRAN  call  that 
has  been  executed,  but  Table  16-6  lists  certain  general  principles 
that  apply.  The  sections  describing  individual  subroutines  provide 
more  details. 
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Table  16-6 
Contents  of  First  Word  of  Isb 


Contents 

Meaning 

isb(l)  -  0 
isb(l)  -  1 
isb(l)  =  3 

3  <  =  isb(l)  <  300 

isb(l)  >  300 

Operation  pending;   I/O  in  progress 

Successful  completion 

Interface  subroutine  unable  to  generate   QIO 
directive,  or  illegal  time  or  buffer  value 

QIO  directive   rejected   and   actual   error 
code  =  -(isb(l)  -  3) 

Driver   rejected   request   and   actual   error 
code  =  -(isb(l)  -  300) 

FORTRAN  ...cerface  routines  depend  on  asynchronous  system  traps  to  set 
their  status.  Thus,  if  the  trap  mechanism  is  disabled,  proper  status 
cannot  be  set. 


16.4.2  Synchronous  Subroutines 

RTS,  DRS,  HIST  (LPSll  only),  SDO,  and  SDAC  are  FORTRAI.'  subroutines 
that  initiate  synchronous  functions.  When  they  are  used,  the 
appropriate  Laboratory  Peripheral  System  driver  and  the  FORTRAN 
program  communicate  by  means  of  a  caller-specified  data  buffer  of  the 
following  format: 


BUF^i:<^  HEADER 


START  OF  DATA 
HALF  BUFFER 
END  OF  BUFFER 


CURRENT  BUFFER  POINTER 


ADDRESS  OF  SECOND  I/O  STATUS  WORD 


ADDRESS  OF  END  OF  BUFFER  +  1 


ADDRESS  OF  START  OF  DATA 


The  buffer  header  is  initialized  when  the  synchronous  function 
initiation  loutine  is  called.  The  length  of  the  buffer  must  be  even 
and  greater  than  or  equal  to  6.  An  even  length  is  required  so  that 
the  buffer  is  exactly  divisible  into  half  buffers. 

The  drivers  perform  double  buffering  within  the  half  buffers.  Each 
time  a  driver  fills  or  empties  a  half  buffer,  it  sets  a  user-specified 
event  flag  to  notify  the  user  task  that  more  data  is  available  or 
needed.  The  user  task  responds  by  putting  more  data  into  the  buffer 
or  by  removing  the  data  now  available. 

It  the  user  task  does  not  respond  quickly  enough,  a  data  overrun  may 
result.  This  occurs  if  the  driver  attempts  to  put  another  data  item 
in  the  user  buffer  when  no  space  is  available  (that  is,  the  buffer  is 
full  of  data),  or  i^  the  driver  attempts  to  obtain  the  next  data  item 
from  the  user  buffer  when  none  is  available  (that  is,  the  buffer  is 
empty) . 
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All  synchronous  functions  can  be  initiated  immediately  or  when  a 
specified  digital  input  point  is  set  (that  is,  a  start  button  is 
pushed) . 

They  can  be  terminated  by  any  combination  of  a  program  request,  the 
processing  of  the  required  number  of  full  buffers  of  data,  or  the 
clearing  of  a  specified  digital  input  point  (that  is,  a  stop  button  is 
pushed).  A  digital  output  point  may  also  optionally  be  set  at  the 
start  of  -  synchronous  function.  This  could  be  used,  for  example,  as 
a  siqnal  o  start  a  test  instrument. 


lfi.4.3  FORTRAN  Subroutine  Summary 

Table  16-7  lists  the  FORTRAN  interface  subroutines  supported  for  the 
Laboratory  Peripheral  Systems  under  RSX-llM.  S  and  F  indicate  whether 
they  can  be  called  as  subroutines  or  functions,  respectively. 

Table  16-7 
FORTRAN  Interface  Subroutines  for  Laboratory  Peripheral  Systems 


Subroutine 

Function 

ADC 

Read  a  single  A/D  channel  (F,S) 

ADJLPS 

Adjust  buffer  pointers  (S) 

ASARLN 

Assign  a  LUN  to  ARO:   (S) 

ASLSLN 

Assign  a  LUN  to  LSO:   (S) 

CVSWG 

Convert  a  switch  gain  A/D  value  to  floating  point 

(F) 

DRS 

Initiate   /ichronous  digital  input  sampling  (S) 

HIST 

Initiate  histogram  sampling  (3)  (LPSll  only) 

IDIR 

Read  digital  input  (F,S) 

I  DOR 

Write  digital  output  (F,S) 

IRDB 

Read  data  from   a   synchronous   function   input   b 
(F,S) 

uf  fer 

LED 

Display  number  in  LED  lights  (S)  (LPSll  only) 

LPSTP 

Stop  an  in- progress  synchronous  function  (S) 

PUTD 

Put  data  into  a  synchronous  function  output  buffer 

(S) 

RELAY 

Latch  an  output  relay  (S)  (LPSll  only) 

RTS 

Initiate  synchronous  A/D  sampling  (S) 

SDAC 

Initiate  synchronous  D/A  output  (S) 

SDO 

Initiate  synchronous  digital  output  (S) 

The  following  subsections  briefly  Jescribe  the  function  and  format  of 
each  FORTRAN  subroutine  call. 
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16.4.4   ADC:  Reading  a  Single  A/D  Channel 

The  ADC  FORTRAN  subroutine  or  functioi.  reads  a  single  converted  value 
from  an  A/D  channel.  If  the  gain-ranging  option  is  present  in  the 
LPSll  hardware,  the  channel  may  be  converted  at  a  specific  gain  or  the 
driver  can  select  the  best  gain  (the  gain  providing  the  most 
significance) .  The  converted  value  is  returned  as  a  normalized 
floating-point  number.   The  call  is  issued  as  follows: 

CALL  ADC  (ichan, [var] , rigain] , [isb] ) 

t 

Ichan 

The  A/D  channel  to  be  converted. 


var 


A  floating-point  variable  that  receives  the   converted   value   in 
floating-point  format. 


Igain 


The  gain  at  which  the  specified  A/D  channel  is  to  be  converted. 
The  default  is  ] .  If  specified,  igain  nay  have  the  following 
values ; 

igain  Gain 

0  Auto   gain-ranging   (driver    selects   gain    that 
provides  most  significance) 

1  1 

2  4 

3  16 

4  64 

A  gain  of  1  is  always  used  by  the  ARll  driver. 

isb 

A  2-word  integer  aTay  to  which  the  subroutine  status  is 
returned . 

The  isb  array  has  the  standard  meaning  described  in  Section  16.4.1. 

When  the  function  form  of  the  call  is  used,  the  value  of  the  function 
is  the  same  as  that  returned  in  var.  If  this  value  is  negative,  an 
error  has  occurred  during  the  A/D  conversion  (see  Section  16.5.3). 
Otherwise,  this  value  is  a  floating-point  number  calculated  from  the 
following  formula: 

var  «  (64  *  converted  value)  /  conversion  gffin 


• 
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16.4.5  ADJLPS:  Adjusting  Buffer  Pointers 

The  ADJLPS  FORTRAiJ  subroutine  adjusts  buffer  pointers  for  a  buffer 
that  a  laboratory  peripheral  system  driver  is  either  synchronously 
filling  or  emptying.  It  is  usually  called  when  indexing  is  being  used 
for  direct  access  to  the  data  in  a  buffer. 

When  data  in  a  buffer  is  to  be  processed  only  once,  the  IRDB  and  PUTD 
routines  may  be  used.  In  some  cases,  however,  it  is  useful  to  leave 
data  in  the  buffer  until  processing  is  complete.  The  user  program  can 
process  the  data  directly,  and  then  call  ADJLPS  to  free  half  the 
buffer.  Using  the  routine  for  synchronous  output  functions  is  quite 
similar.  When  a  half  buffer  of  data  is  ready  for  output,  ADJLPS  is 
called  to  make  the  half  buffer  available. 

When  ADJLPS  is  used  for  either  input  or  output,  care  must  be  taken  to 
insure  that  the  program  stays  In  sync  with  the  driver.  If  the  program 
loses  Its  position  with  respec;  to  the  driver,  the  function  must  be 
stopped  and  restarted.  An  attempt  to  over-adjust  will  cause  a  3  to  be 
returned  in  isb(l)  and  no  adjustment  to  take  place. 

The  call  is  issued  as  follows: 

CALL  ADJLPS  ( ibuf , lad j  ,  [  Iso) ) 


ibuf 


iadj 


isb 


An  Integer  array  that  was  previously  specified  In   a   synchronous 
input  or  output  function. 


The  adjustment  to  be  applied  to  the  buffer  pointers.  For  an 
input  function,  this  specifies  the  number  of  data  values  that 
have  been  removed  from  the  data  buffer.  For  an  output  function, 
this  specifies  the  number  of  data  values  that  have  been  put  into 
the  data  buffer. 


A   2-word   integer  array  to  which   the   subroutine   status   Is 
returned . 


The  Isb  array  has  the  standard  meaning  described  in  Section  16.4.1. 


16.4.6   ASLSLN:  Assigning  a  LUN  to  LSO: 

The  ASLSLN  FORTRAN  subroutine  assigns  a  logical  unit  number  (LUN)  to 
the  LPSll.  It  must  be  called  prior  to  executing  any  other  Laboratory 
Peripheral  Systems  FORTRAN  function  or  subroutine.  Subsequent  calls 
to  other  Interface  routines  then  implicitly  reference  the  LPSll  with 
the  LUN  assigned. 
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The  call  is  issued  as  follows: 

CALL  ASLSLN  (lun, [ isb] , t iun] ) 

lun 

Th«  number  of  the  LUN  to  bt   assigned  to  LSO: 

A  2-word   integer  array  to  which  the  subroutine  status   Is 
returned. 

lun 

The  unit  number  of  the  device  to  be  assigned  (defaults   to   0   if 
not  specified) . 

The  isb  array  has  the  standard  meaning  described  in  Section  16.4.1. 


16.4.7  A5ARLN:  Assigning  a  LUN  to  ARO: 

The  ASARLN  FORTRAN  subroutine  assigns  a  logical  unit  number  (LUN)  to 
the  ARll.  It  must  be  called  prior  to  executing  any  other  laboratory 
peripheral  system  FORTRAN  function  or  subroutine.  Subsequent  calls  to 
other  interface  routines  then  implicitly  reference  the  ARll  with  the 
LUN  assigned. 

The  call  is  issued  as  follows: 

CALL  ASARLN  (lun , [ isb] , [ iun] ) 

lun 

The  number  of  the  LUN  to  be  assigned  to  ARO:. 

isb 

A   2-word   integer   array  to  which   the   subroutine   status   is 
returned. 

iun 

The  unit  number  of  the  device  to  be  assigned  (defaults   to   0   if 
not  specified) . 

The  isb  array  has  the  standard  meaning  described  in  Section  16.4.1. 
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16.4.8  CVSWG:  Converting  a  Switch  Gain  A/D  Value  to  Floating-Point 

The  CVSWG  FORTRAN  subroutine  converts  an  A/D  value  from  a  synchronous 
A/D  sampling  function  to  a  floating-point  number.  Each  data  item 
returned  by  a  laboratory  peripheral  system  driver  consists  of  a  gain 
code  and  converted  value  packed  in  a  single  word  (see  Section 
16.3.3.1).  This  form  is  not  readily  usable  by  FORTRAN,  but  is  much 
more  efficient  than  converting  each  value  to  floating  point  in  the 
driver.  This  routine  unpacks  the  gain  code  and  value,  and  then 
converts  the  result  to  a  floating-point  number.  It  can  be 
conveniently  used  in  conjunction  with  the  IRDB  routine  (see  Section 
16.4.13) . 

The  call  is  issued  as  follows: 

CVSWG  (ival) 

ival 

The  value  to  be  converted  to  floating  point.  Its  format  must  be 
that  returned  by  a  synchronous  A/D  sampling  function.  The 
conversion  is  performed  according  to  the  following  formula: 

var  =  (64  *  converted  value) /conversion  gain 

For  the  various  gain  codes, 

var  =  X  *  converted  value 

as  shown  below: 

Gain  x 

1  64 

4  16 

16  4 

64  1 

16.4.9  DRS;  Initiating  Synchronous  Digital  Input  Sampling 

The  DRS  FORTRAN  subroutine  reads  data  qualified  by  a  mask  word  from 
the  digital  input  register  at  precisely  timed  intervals.  Sampling  may 
be  started  or  stopped  as  for  RTS  (see  Section  16.4.18)  and  all  input 
is  double  buffered  with  respect  to  the  user  task.  Data  may  be 
sequentially  retrieved  from  the  data  buffer  by  the  IRDB  routine  (see 
Section  16.4.12),  or  the  ADJLPS  routine  (see  Section  16.4.5)  may  be 
used  in  Tonjunction  with  direct  access  to  the  input  data.  The  call  is 
issued  as  follows: 

CALL  DRS  (ibuf,ilen,imode, irate, iefn,iraask,isb, [nbuf] , 
[istart] , t istopj ) 
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ibuf 

An  integer  array  that  is  to  receive  the  input  data  values. 

ilen 

The  length  of  ibuf  (must  be  even  and  greater  than  or  equal  to  6). 
Imode 

The  start,  stop,  and  sampling  mode.  Its  value  is  encoded  by 
adding  together  the  appropriate  function  selection  values  shown 
below.  ^ 

Function 
Selection 
Value  Meaning 

12&'       Start  on  digital  input  point  set 

ft4       Set  digital  output  point  at  start 

32       Stop  on  digital  input  point  clear 

16       Stop  on  number  of  buffers 

Thus,  a  value  of  192  for  imode  specifies: 

•  The  sampling  is  to  be  started  when  a  specified  dioital   input 
point  is  set. 

•  A  digital  output  point  is  to  be  set  when  sampling  is  started. 

•  Sampling  will  be  stopped  by  a  program  request. 


irate 


iefn 


A  2-word  integer  array  that  specifies  the  time  interval  between 
digital  input  sanples.  The  first  word  specifies  the  interval 
units  as  follows: 

irate(l)  unit 

1  Real-time  clock  ticks 

'i.  Milliseconds 

3  Seconds 

4  Minutes 

The  second  word  specifies  the  interval  magnitude  as  a  16-bit 
unsigned  integer. 


The  number  of  the  event  flag  that  is  to  be  set  each  time   a   half 
buffer  of  data  has  been  collected. 
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imask  '   * 

The  digital  input  points  to  be  read. 


isb 


A  2-word   integer   array  to  which   the   subroutine  status   is 
returned. 


nbuf 


The  number  of  buffers  of  data  to  be  collected.   It  is  needed  only 
if  a  function  '.  x.'Ction  value  of  16  has  been  added  into  imode. 


istart 


The  digital  input  pointer  number  to  be  used  to  trigger  sampling, 
and/or  the  digital  output  point  number  to  be  set  when  sampling  is 
started.  It  is  needed  only  if  a  function  selection  value  of  128 
or  64  has  been  added  into  imode. 

istop 

The  digital  input  point  number  to  be  used  to  stop  sampling.  It 
is  needed  only  if  a  function  selection  value  of  32  has  been  added 
into  imode. 

Wh'-n  sampling  is  in  progress,  the  first  word  of  the  isb  array  is  zero 
and  the  second  word  contains  the  number  of  data  values  currently  in 
the  buffer. 


16.4.10  HIST:  Initiating  Histogram  Sampling  (LPSll  only) 

The  HIST  FORTRAN  subroutine  measures  the  elapsed  time  between  a  series 
of  events  with  Schmitt  trigger  1. 

Each  time  a  sample  is  to  be  taken,  a  counter  is  incremented  and 
Schmitt  trigger  1  is  tested.  If  it  has  fired,  then  the  counter  is 
written  into  the  user  buffer  and  the  counter  is  reset  to  0.  Thus  the 
data  returned  to  the  user  is  the  number  of  sample  intervals  between 
Schmitt  trigger  firings.  If  the  counter  overflows  before  Schmitt 
trigger  1  fires,  a  0  value  is  written  into  the  user  buffer.  Sampling 
may  be  started  and  stopped  as  for  RTS  (see  Section  16.4.18)  and  all 
input  is  double  buffered  with  respect  to  the  user  task.  The  call  is 
issued  as  follows: 

CALL  HIST  { ibuf , ilen , imode, irate , iefn , isb, [nbuf ]  , 
[istart] , [ istop] ) 

ibuf 

An  integer  array  that  is  to  receive  the  input  data  values. 
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ll«n 

The  length  of  Ibuf  (must  be  even  and  greater  than  or  equal  to  6) . 
Imode 

The  start,  stop,  and  sampling  mode.    Its   value   is  enoded   by 
adding  the  appropriate  function  selection  values  shown  below: 

Function 
Selection 
Value  Meaning 

128  Start  of  digital  input  point  set 

64  Set  digital  output  point  at  start 

32  Stop  on  digital  input  point  clear 

16  Stop  on  number  of  buffers 


irate 


A  2-wori  integer  array  that  specifies  the  time   interval   between 
samples.   The  first  word  specifies  the  intfci.val  units  as  follows: 

irate(l)  Unit 

1  Real-time  clock  ticks 

2  Milliseconds 

3  Seconds 

4  Minutes 


The  second  word  specifies  the   interval   magnitude  as   a   16-bit 
signed  integer. 


iefn 

The  number  of  the  event  flag  that  is  to  be  set  each  time   a   half 
buffer  of  data  has  been  collected. 

isb 

A   2-word   integer   array  to   which   the   subroutine   status   is 
returned, 
nbuf 

The  number  of  buffers  of  data  to  be  collected.   It  is  needed  only 
if  a  functicti  selection  value  of  16  has  been  added  into  imode. 
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Istart 


The  digital  input  point  number  to  be  used  to  trigger  sampling 
and/ur  the  digital  output  point  number  to  be  set  when  sampling  is 
started.  It  is  needed  only  if  a  function  selection  value  of  128 
or  64  has  been  added  into  imode. 

istop 

The  digital  input  point  number  to  be  used  to  stop  sampling.  It 
is  needed  only  if  a  function  selection  value  of  32  has  been  added 
into  imode. 

The  isb  array  has  the  standard  meaning  described  in  Section  16.4.1. 

When  sampling  is  in  progress,  the  first  word  of  the  isb  array  is  0  and 
the  second  word  contains  the  number  of  data  values  currently  in  the 
buffer. 


16.4.11   IDIR:  Reading  Digital  Input 

The  IDIR  FORTRAN  subroutine  or  function  rends  the  digital  input 
register  as  an  unsigned  binary  Integer,  or  as  four  binary-coded 
decimal  (BCD)  digits.  In  the  latter  case,  the  BCD  digits  are 
converted  to  a  binary  integer  before  the  value  is  returned  to  the 
caller.   The  call  is  issued  as  follows: 

CALL  IDIR  (imode, fival] ,( isb] ) 

imode 

The  mode  in  which  the  digital  input  register  is  to  be  read.  If 
imode  equals  0,  then  the  digital  input  register  is  read  as  four 
BCD  digits  and  converted  to  a  binary  integer.  Otherwise,  it  is 
read  as  a  16-bit  unsigned  binary  integer. 

ival 

A  variable  that  receives  the  value  read. 

Isb 

A  2-word  integer  array  to  which  the  subroutine  status  is 
returned . 

The  isb  array  has  the  standard  meaning  described  in  Section  16.4.1. 

When  the  function  form  of  the  call  is  used,  the  value  of  the  function 
is  the  same  as  that  returned  in  ival. 


16-19 


LABORATORY  PBRTPHERAL  SYSYBMS  DRIVERS 

16.4.12  IDOR:  Writing  Digital  Output 

The  IDOR  FORTRAN  subroutine  or  function  clears  or  sets  bits  in  the 
digital  output  register.  The  caller  provides  a  mask  word  and  output 
mode.  Bits  in  the  digital  output  regictf-s  corresponding  to  the  bits 
specified  in  the  mask  word  are  either  set  or  cleared  according  to  the 
specified  mode.   The  call  is  issued  as  follows: 

CALL  IDOR  (imode,imask, [newval] , [ isb] ) 

imode 

Whether  the  bits  specified  by  imask  are  to  be  cleared  or  set  in 
the  digital  output  register.  If  imode  equals  0,  then  the  bits 
are  to  be  cleared.   Otherwise,  they  are  to  be  set. 


Imask 


The  bits  to  be  clearer!  or  set  in  the  digital  output  register.   It 
may  be  conveniently  specified  as  an  octal  constant. 


netrval 


A  variable  that  receives  the  updated  (actual)  value  written   into 
the  digital  output  register. 


isb 


A  2-word   integer  array  to  which   the   subroutine   status   is 
returned . 

The  isb  array  has  the  standard  meaning  described  in  Section  16.4.1. 

When  the  function  form  of  the  call  is  used,  the  value  of  the   function 
is  the  same  as  that  returned  in  newval. 


16.4.13   IRDB:  Reading  Data  from  an  Input  Buffer 

The  IRDB  FORTRAN  subroutine  or  function  retrieves  data  sequentially 
from  a  buffer  that  a  laboratory  peripheral  system  driver  is 
synchronously  filling.  If  no  data  is  available  when  the  call  is 
executed,  the  contents  of  the  next  location  in  the  data  buffer  are 
returned  without  updating  the  buffer  pointers.  The  call  is  issued  as 
follows: 

CALL  IRDB  (Ibuf ,[ival] ) 


# 
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ibuf 

An  integer  array  that  was  previously  specified  in  a  synchronous 
input  sampling  request  (that  is,  DRS,  HIST,  or  RT.'^. 

ival 

A  variable  that  receives  the  next  value  in  the  data  buffer. 

When  the  function  form  of  the  call  is  used,  the  value  of  the   function 
is  the  same  as  that  returned  in  ival. 


lfi.4.14   LED:  Displaying  in  LED  Lights  (LPSll  only) 

The  LED  FORTRAN  subroutine  displays  a  16-bit  signed  binary  integei  in 
the  LED  lights.  The  number  is  displayed  with  a  leading  blank 
(positive  number)  or  minus  (negative  number) ,  followed  by  five 
non-zero-suppressed  decimal  digits  that  represent  the  magnitude  of  the 
number.  LED  digits  are  numbered  right  to  left  starting  at  1  and 
continuing  to  5.  The  number  may  be  displayed  with  or  without  a 
decimal  point.   The  call  is  issued  as  follows: 

CALL  LED  (ival,  [idee]  ,  [isb] ) 

ival 

The  variable  whose  value  is  to  be  displayed. 

idee 

The  position  of  the  decimal  point.  A  value  of  1  to  5  specifies 
that  a  decimal  point  is  to  be  displayed.  All  other  values 
specify  that  no  decimal  point  is  to  be  displayed. 


isb 


A   2-word   integer   array  to   which   the  subroutine   status   is 
returned . 


The  isb  array  has  the  standard  meaning  described  in  Section  16.4.1, 
For  example,  the  following  call: 

CALL  LED  (-55,2) 
would  cause  -0005.5  to  be  displayed  in  the  LED  lights. 
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16.4.15  LPSTP:  Stopping  an  In-Progr«s8  Synchronous  Function 

The  LPSTP  FORTRAN  subroutine  selectively  stops  a   single   synchronous 
request.   The  call  is  issued  as  follows: 

CALL  LPSTP  (ibuf) 

Ibuf 

An  integer  array  that  specifies  a  buffer   that  was  previously 
specified  in  a  synchronous  initiation  request. 


16.4.  lf>  PUTD:  Putting  a  Data  Item  into  an  Output  Buffer 

The  PUTD  FORTRAN  subroutine  puts  data  sequentially  into  a  buffer  that 
a  laboratory  peripheral  system  driver  is  synchronously  emptying.  If 
no  free  space  is  available,  no  operation  is  performed.  The  call  is 
issued  as  follows: 

CALL  PUTD  (ibuf,ival) 

ibuf 

An  integer  ar^ay  which  was  previously  specified  in  a   synchronous 
output  request  (SDO  or  SDAC) . 


ival 


A  variable  whose  value  is  to  be  placed  in  the  next  free   location 
in  the  data  buffer. 


16.4.17  RELAY:  Latching  an  Output  Relay  (LPSll  only) 

The  RELAY  FORTRAN  subroutine  opens  or  closes  the   LPSll   relays.    The 
call  is  issued  as  follows: 

CALL  RELAY  ( irel , istate , [ isb] ) 

irel 

Which  relay  is  to  be  opened  or  closed  (0  for   relay  one,   1   for 
relay  two) . 


istate 


Whether  the  relay  is  to  be  opened  or  closed.   If  istate  equals  0, 
the  relay  is  to  be  opened.   Otherwise,  it  is  to  be  closed. 


Isb 


A   2-word   integer   array  to  which   the   subroutine   status   is 
returned . 

The  isb  array  has  the  standard  meaning  described  in  Section  16.4.1. 
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l<i.4.18   RTS:  Initiating  Synchronous  A/D  Sampling 

The  RTS  PODTRAN  subroutine  reads  one  or  more  A/D  channels  at  precisely 
timed  intervals,  with  or  without  auto  gain-ranging.  The  auto 
•J** p-ranging  algorithm  (LPSll  only)  causes  the  channels  to  be  sampled 
at  the  highest  gain  at  which  saturation  does  not  occur. 

Sampling  can  be  started  when  the  interface  subroutine  is  called  or 
when  a  specified  digital  input  point  is  set.  A  digital  output  point 
can  optionally  be  set  when  sampling  is  started.  Sampling  can  be 
terminated  by  a  program  request  (stop-in-progress  request  or  kill 
I/O),  the  clearing  of  a  digital  input  point,  or  the  collection  of  a 
specified  number  of  buffers  of  data. 

All  input  is  double  buffered  with  respect  to  the  user  task.  Each  time 
a  half  buffer  of  data  has  been  collected,  the  user  task  is  notified 
(by  the  setting  of  an  event  flag)  that  data  is  available  to  be 
processed  while  the  driver  fil  '  the  other  half  of  the  buffer.  Data 
can  be  sequentially  retrieved  from  the  data  buffer  with  the  IRDB 
routine  (see  Section  16.4.12),  or  the  ADJLPS  nutine  (see  Section 
16.4.5)  can  be  used  in  conjunction  with  direct  access  to  the  input 
data.   The  call  is  issued  as  follows: 

CALL  RTS  (ibuf, ilen, imode, irate, iefn, ich^n,nchan,isb, 
[nbuf 1 , (i start! , [istopl ) 

ibuf 

An  integer  array  that  is  to  receive  the  converted  data  values. 

ilen 

The  length  of  ibuf  (must  be  even  and  greater  than  or  equal  to  6). 


imode 


The  start,  stop,  and  sampling  mode.  Its  value  is  encoded  by 
adding  together  the  appropriate  function  selection  values  as 
shown  below: 


Function 
Selection 
Value  Meaning 


128  Start  on  digital  input  point  set 

64  Set  digital  output  point  at  start 

32  Stop  on  digital  input  point  clear 

16  Stop  on  number  of  buffers 

8  Auto  gain-ranging  (IPSll  only) 


16-23 


LABORATORY  PERIPHERAL  SYSTEMS  DRIVERS 


irate 


A  2-worcl  integer  array  that  specifies  the  time  interval  between 
A/D  samples.  The  first  word  specifies  the  interval  unit  as 
follows: 

Irate(l)  Unit 

1  Real-time  clock  ticks 

2  Milliseconds 

3  Seconds 

4  Minutes 

The  second  word  specifies  the  interval  magnitude  as  a  16-bit 
unsigned  integer. 


iefn 


The  number  of  the  event  flag  that  is  to  be  set  each  time  a   half 
buffer  of  data  has  been  collected. 


ichan 


The  starting  A/D  channel  of  the  block  of  channels  to  be  sampled 
synchronously  (must  be  between  0  and  63  for  LPSll  and  between  0 
and  15  for  ARll) . 


nchan 


Isb 


The  number  of  A/D  charnels  to  be  sampled  (must  be  between   1   and 
64  for  LPSll  and  between  1  and  16  for  ARll). 


A   2-word   integer  array  to  which   the   subroutine   status   is 
returned. 


nbuf 


The  number  of  buffers  of  data  that  are  to  be  collected.  It  is 
needed  only  if  a  function  selection  value  of  16  has  been  added 
into  imode. 


istart 


The  digital  input  point  number  to  be  used  to  trigger  sampling 
and/or  the  digital  output  point  number  to  be  set  when  sampling  is 
started.  It  is  needed  only  if  a  function  selection  value  of  128 
or  64  has  I  ^n  added  into  imode.  Points  are  numbered  from  0  to 
15,  allowing   maximum  of  16  points  tc  be  specified. 


istop 


The  digital  input  point  number  to  be  used  to  stop  sampling.  It 
is  needed  only  if  a  function  selection  value  of  32  has  been  added 
into  imode. 
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The  values  listed  for  ichan  and  nchan  above  are  the  maximum  allowable 
for  each  of  the  devices.  In  practice,  they  are  constrained  by  the 
number  of  channels  available  as  specified  during  SYSGEN. 

The  isb  parameter  has  the  standard  meaning  described  in  Section 
16.4.1. 

When  sampling  is  in  progress,  the  first  word  of  the  isb  array  is  0  and 
the  second  word  contains  the  number  of  data  values  currently  in  the 
buffer. 


16.4.19   SDAC:  Initiating  Synchronous  D/A  Output 

The  SDAC  FORTRAN  subroutine  writes  data  into  one  or  more  external  D/A 
converters  at  precisely  timed  intervals.  Output  may  be  started  and 
s  V  ed  as  for  RT3  (see  Section  16.4.18),  and  all  input  is  double 
bu  jred  with  respect  to  the  user  task.  One  full  buffer  of  data  must 
be  available  when  synchronous  outpuL  is  initiated. 

After  SDAC  has  initiated  output  and  the  specified  event  flag  has  been 
set  to  notify  the  task  that  free  buffer  space  is  available,  the  PUTD 
routine  (see  Section  16.4.16)  may  be  used  to  put  data  ''alues 
sequentially  into  the  output  data  buffer.  The  ADJLPS  routine  (see 
Section  16.4.5)  may  be  used  in  conjunction  with  direct  access  to  the 
output  data  buffer.   The  SDAC  call  is  issued  as  follows: 

CALL  SDAC  ( ibuf, ilen, imode, i rate , iefn, ichan, nchan, isb, 
[nbufl , [istart] , [istopl ) 

ibuf 

An  integer  array  that  contains  the  output  data  values. 

ilen 

The  length  of  ibuf  (must  be  even  ana  greater  than  or  equal  to  6) . 


imode 


The  start,  stop,  and  sampling  mode.  Its  value  is  encoded  by 
adding  together  the  appropriate  function  selection  values  as 
shown  below: 


Meaning 

Start  on  digital  input  point  set 
Set  digital  output  point  at  start 
Stop  on  digital  input  point  clear 
Stop  on  number  of  buffers 


Function 

Selection 

Value 

128 

64 

32 

16 
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Irat* 

A  2-word  integer  array  th.it  specifies  the  time   interval   between 
D/A  outputs.   The  first  word  specifies  the  interval  units  as 


follows: 

Iratad) 

Unit 

1 

Real-time  clock  ticks 

1 

Milliseconds 

3 

Seconds 

4 

Minutes 

The  second  word  specifies  the   interval   magnituda  as   a   If-bit 
unsigned  integer. 


iefn 


The  number  of  the  event  flag  that  is  to  be  set  each  time  a  half 
buffer  of  data  has  been  output. 

ichan 

The  starting  D/A  channel  of  the  block  of  channels  to  be  written 
into  synchronously  (must  be  between  0  and  9  for  LPSll,  and  be  0 
or  1  for  ARID  . 

nchan 

The  number  of  D/A  channels  to  be  written  into  (must  be  between  1 
and  10  for  LPSll,  and  be  1  or  2  for  ARll). 


isb 


A  2-word   integer   array   to  which   the   subroutine   status   is 
returned. 


nbuf 


The  number  of  buffers  of  data  to  be  output.   It  is  needed  only  if 
a  function  selection  value  of  Ifi  has  been  added  into  imode. 


istart 


The  digital  input  point  number  to  be  used  to  trigger  sampling 
and/or  the  digital  output  point  number  to  be  set  when  sampli.-ig  is 
started.  It  is  needed  only  if  a  function  selection  value  of  128 
or  64  has  been  added  into  imode.  Points  are  numbered  from  0  to 
15,  allowing  a  maximum  of  Ifi  points  to  be  specified. 
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Istop 

The  digital  input  point  number  to  be  used  to  stop  sampling.  It 
is  needed  only  if  a  function  selection  value  of  31  has  been  added 
into  imode. 

The  irb  array  has  the  standard  meaning  described  in  Section  16.4.1. 

When  sampling  is  in  progress,  the  first  word  of  the  isb  array  is  0  and 
the  second  word  contains  the  number  of  free  positions  in  the  buffer. 


16.4.20  SDO:  Initiating  Synchronous  Digital  Output 

The  SDO  FORTRAN  subroutine  writes  data  qualified  by  a  mask  word  into 
the  digital  output  register  at  precisely  timed  intervals.  Sampling 
may  be  started  and  stopped  as  for  RTS  (see  Section  16.4.18)  and  all 
input  is  double  buffered  with  respect  to  the  user  task.  One  full 
buffer  of  data  must  be  available  when  output  is  initiated. 

After  SDO  nas  initiated  output,  and  the  specified  event  flag  has  been 
set  to  notify  the  task  that  free  buffer  space  is  available,  the  PUTO 
routine  (see  Section  16.'  16)  may  be  used  to  put  data  values 
sequentially  into  the  output  data  buffer.  The  ADJLPS  routine  ("36 
Section  16.4.5)  may  be  used  in  conjunction  wifh  direct  access  to  the 
output  data  buffer.   The  3D0  call  is  issued  as  follows: 

CALL  SDO  (ibuf ,ilen, imode, irate, iefn, imask, isb, tnbuf] , 
[istart] , (istopl ) 

ibuf 

An  integer  array  that  contains  the  digital  output  values. 

lien 

The  length  of  ibuf  (must  be  even  and  greater  than  or  equal  to  6). 


inode 


The  start,  stop,  and  sampling  mode.  Its  value  is  encoded  by 
adding  together  the  appropriate  function  selection  values  as 
shown  below: 

Function 
Selection 
Value  Meaning 

128  Start  on  digital  input  point  set 

#4  Set  digital  output  point  at  start 

32  Stop  on  digital  input  point  clear 

IC  Stop  on  number  of  buffers 
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Irat* 

A  2-word  integer  array  that  specifies  the  time  interval  between 
digital  outputs.  The  first  word  specifies  the  interval  units  as 
follows: 

irate(l)  Unit 

X  Real-time  clock  ticks 

2  Milliseconds 

3  Seconds 

4  Minutes 

The  second  word  specifies  the  interval  magnitude  as  a  16-bit 
unsigned  integer. 


iefn 


The  number  of  the  event  flag  that  is  to  be  set  each  time  a  half 
buffer  of  data  has  been  output. 


imask 


isb 


The  digital  output  p)ints  that  are  to  be  written.   It  may  be 
conveniently  specified  as  an  octal  constant. 


A  2-word   integer  array  to  which  the  subroutine  status   is 
returned. 


nbuf 


The  number  of  buffers  of  data  to  be  output.   It  is  needed  only  if 
a  function  selection  value  of  16  has  been  added  into  imode. 


istart 


The  digital  input  point  number  to  be  used  to  trigger  sampling 
and/or  the  digital  output  point  number  to  be  set  when  sampling  is 
started.  It  is  needed  only  if  a  function  selection  value  of  128 
cr  64  has  been  added  into  imode.  Points  are  numbered  0  through 
15,  allowing  a  maximum  of  16  points  to  be  specified. 

istop 

The  digital  input  point  number  to  b-  used  to  stop  sampling.  It 
is  needed  if  a  function  selection  value  of  32  has  been  added  into 
imode. 

The  isb  parameter  has  the  standard  meaning  described   in  Section 
16.4.1. 

When  sampling  is  in  progress,  the  first  word  of  the  isb  ariay  is  0  and 
the  second  word  contains  the  number  of  free  positions  in  the  buffer. 
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16.5   STATUS  RETURNS 

The  error  and  status  conditions  listed  in  Table  16-8  are  returned  by 
the  Laboratory  Peripheral  System  drivers  described  in  this  chapter. 


Table  16-8 
Laboratory  Peripheral  Systems  Status  Returns 


m 


Code 

Reason 

IS. sue 

Successful  completion 

The  operation  specified  in  the  QIC  directive  was 
completed  successfully.  The  second  word  of  the 
I/O  status  block  can  be  examined  to  determine  the 
number  of  data  values  processed. 

IS.PND 

I/O  request  pending 

The  operation  specified  in  the  010  directive  has 
not  yet  been  completed. 

IE. ABO 

Operation  aborted 

The  specified  I/O  operation  was  canceled  (by 
lO.KIL  or  lO.STP)  while  in  progress. 

IE. BAD 

Bad  parameter 

An  illegal  specification  was  supplied  for  one  or 
more  of  the  device-dependent  QIO  porameters  (words 
6-11).  The  second  I/O  status  word  is  filled  with 
Os. 

IE. BYT 

Byte-aligned  buffer  specified 

Byte  alignment  was  specified  for  a  data  buffer  but 
only  word  alignment  is  legal  for  Laboratory 
Peripheral  Systems.  Alternatively,  the  length  of 
a  buffer  is  not  an  even  number  of  bytes. 

lE.DAO 

Data  overrun 

For  Laboratory  Peripheral  Systems,  the  driver 
attempted  to  get  a  value  from  the  user  buffer  when 
none  was  available  or  attempted  to  put  a  value  in 
the  user  buffer  when  no  space  was  available. 

lE.DNR 

Device  not  ready 

The  physical  device  unit  specified  in  the  QIO 
directive  was  not  ready  to  perform  the  desired  I/O 
operation.  For  Laboratory  Peripheral  Systems, 
this  code  is  returned  if  a  device  time-out  occurs 
while  a  function  is  in  progress.  The  second  I/O 
status  word  contains  the  number  of  free  positions 
in  the  buffer,  as  appropriate. 

(continued  on  next  page) 
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Table  16-8   (Cont.) 
Laboratory  Peripheral  Systems  Status  Returns 


Code 

Reason 

lE.IEF 

Invalid  event  flag  number 

An  invalid  event  flag  number  was  specified  in  a 
synchronous  function. 

IE. IPC 

Illegal  function 

A  function  code  was  included  in  an  I/O  request 
that  is  illegal  for  the  LPSll  or  AR1\ 

IE. NOD 

Insufficient  buffer  space 

_ 

Dynamic  storage  space  has  been  leted,  and  there 
is  insufficient  buffer  space  available  to  allocate 
a  secondary  control  block  for  a  synchronous 
function. 

lE.OFL 

Device  off  line 

The  physical  device  unit  associated  with  the  LUN 
specified  in  the  QIO  directive  was  not  on  line. 
When  the  system  was  booted,  a  device  check 
indicated  that  this  physical  device  unit  was  not 
in  the  configuration. 

lE.ONP 

Option  not  present 

An  option  dependent  function  or  subfunction  was 
requested,  and  the  required  feature  was  not 
specified  at  system  generation.  For  example  the 
gain-ranging  option  or  D/A  option  is  not  present. 
The  second  I/O  status  word  contains  0, 

lE.PRI 

Privilege  violation 

The  task  which  issued  the  request  was  not 
privileged  to  execute  that  request.  For 
Laboratory  Peripheral  Systems,  a  checkpointable 
task  attempted  to  execute  a  synchronous  sampling 
function. 

lE.RSU 

Resource  in  use 

A  resource  needed  by  the  function  requested  in  the 
QIO  directive  was  being  used  (see  Section  16.5.1). 

lE.SPC 

Illegal  address  spacd 

The  buffer  specified  for  a  read  or  write  request 
was  partially  or  totally  outside  the  address  space 
of  the  issuing  task.  Alternately  a  byte  count  of 
0  was  specified.  The  second  I/O  status  word 
contains  0. 

FORTRAN  interface  values  for  these  status   returns   are   presented   in 
Section  16,5.4. 
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16.5.1   lE.RSU 


lE.RSU  is  returned  if  a  function  requests  a  resource  that  is  currently 
being  used.  The  requesting  task  may  repeat  the  request  at  a  later 
time  or  take  any  alternative  action  required. 

Because  certain  functions  do  not  need  such  resources,  they  never  cause 
this  code  to  be  returned.  Other  functions  return  this  code  under  the 
following  conditions: 


Function 
lO.SDO 

10. ADS 
10. HIS 
lO.MDA 
lO.MDI 

lO.MDO 


When  lE.RSU  Is  Returned 

One  or  more  specified  digital  output  bits  are  in 
use. 


Digital  output  point  ( 

Digital  output  point  ( 

Digital  output  point  ( 

)igital  output  point  ( 


input  points  to  be  sampled  are  in  use 


Digital  output  point  ( 


f  specified)  is  in  use. 

f  specified)  is  in  use. 

i  specified)  is  in  use. 

f  specified)  or  digital 


to  be  written  are  in  use. 


f  specified)  or  output  bits 


The  following  components  of  the  Laboratory  Peripheral  Systems  are  each 
considered  a  single  resource: 


Resource 

The  A/D  Converter 
and  clock 

Each  bit  in  the 
digital  output 
register 

Each  bit  in  the 
digital  input 
register 


When  Shareable 
Always  shareable 

Never  shareable. 


Always  shareable  when  used  by  lO.SDI 
or  for  start/stop  conditions  (specified 
in  subfunction  modifier  bits),  even  when 
in  use  by  another  function;  when 
specified  by  a  synchronous  digital  input 
function,  not  shareable  with  another 
such  function 


Each  resource  is  allocated  on  a  first-come-first-served  basis.  (That 
is,  when  a  conflict  arises,  the  most  recent  request  is  rejected  with  a 
status  of  lE.RSU) . 


16.5.2   Second  I/O  Status  Word 

On  successful  completion  of  a  function  specified  in  a  QIC  macro   call, 
the  IS. sue  code  is  returned  to  the  first  word  of  the  I/O  status  block. 

Table  lfi-9  lists  the  contents  of  the  second  wjrd  of  the  status   block, 
on  successful  completion  for  each  function. 
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Table  16-9 
Returns  to  Second  Word  of  I/O  Status  Block 


Successful 

Function 

Contents  of  Second  Word 

lO.KIL 

Number  of  data  values  before  I/O  was  canceled 

10. LED 

0 

lO.REL 

0 

lO.SDI 

Masked  value  read  from  digital  input  register 

lO.SDO 

Updated  value  written  into  digital  output  register 

10. ADS 

Number  of  data  values  remaining  in  buffer 

10. HIS 

Number  of  data  values  remaining  in  buffer 

lO.MDA 

Number  of  free  positions  in  buffer 

lO.MDI 

Number  of  data  values  remaining  in  buffer 

lO.MDO 

Number  of  free  positions  in  buffer 

lO.STP 

0 

When  IE. BAD  is  returned,  the  second  I/O  status  word  contains  0/ 
Laboratory  Peripher  'Systems  drivers  return  the  IE. BAD  code  under  the 
following  conditioi 


Function 


When  IE. BAD  is  Returned 


lO.REL 

10. ADS 
lO.MDA 

10. HIS 
lO.MDI 
lO.MDO 


Relay  number  not  0  or  1 

No  I/O  status  block,  illegal  digital  I/O  point 
number,  or  illegal  channel  number 

No  I/O  status  bl^ck  or  illegal 
digital  I/O  point  number 


16.5.3   10. ADS  and  ADC  Errors 

While  10. ADS  or  the  ADC  FORTRAN  subroutine  is  converting  a  sample,  two 
error  conditions  may  arise.  Both  of  these  conditions  are  reported  to 
the  user  by  placing  illegal  values  in  the  data  buffer.  A  -1 
(177777(8)  is  placed  in  the  buffer  if  an  A/D  conversion  does  not 
complete  within  30  microseconds.  A  -2  (177776(8)  is  placed  in  the 
buffer  if  an  error  occurs  during  an  A/D  conversion  (LPSll  only). 
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16.5.4  FORTRAN  Interface  Values 

The  values  listed  in  Table  16-10  are  returned   in  FORTRAN  subroutine 
calls. 


Table  16-10 
FORTRAN  Interface  Values 


• 


Status  Return 

FORTRAN  Value 

IS. sue 

♦01 

I S . PND 

♦  00 

I  E.ABO 

♦  315 

lE.ADP 

♦  101 

lE.ALN 

♦  334 

IE. BAD 

♦  301 

IE. BYT 

♦  319 

I E . DAO 

♦  313 

lE.DNR 

♦  303 

lE.IEF 

♦  100 

lE.IFC 

♦  302 

lE.ILU 

♦  99 

IE. NOD 

♦  323 

lE.OFL 

♦  365 

JE.ONP 

♦  305 

I E .  PR  I 

♦  316 

lE.RSU 

♦  317 

IE. SOP 

♦  102 

lE.SPC 

♦  306 

lE.ULN 

♦  08 

lE.UPN 

♦  04 

• 


16.6   PROGRAMMING  HINTS 

This  section  contains  information  on  important  programming 
considerations  relevant  to  users  of  the  Laboratory  Peripheral  Systems 
drivers  described  in  this  chapter. 


16.6.1   The  LPSll/ARll  Clock  and  Sampling  Rates 

The  basic  real-time  clock  frequency  (count  rate)  for  all  synchronous 
functions  is  always  lOKHz.  Device  characteristics  word  4  contains  a 
Ifi-bit  buffer  preset  value  --  set  dynamically  or  at  system  generation, 
that  controls  the  rate  of  "ticks"  (that  is,  the  rate  at  which  the 
clock  interrupts).  ',"  e  quotient  that  results  when  this  value  is 
divided  into  lOKHz  is  the  rate  of  "ticks."  For  example,  if  this  value 
is  2,  the  "tick"  rate  is  5KHz.  The  user  can  use  a  Get  LUN  Information 
system  directive  to  examine  the  value  and  a  SET  /BUF  MCR  function  to 
modify  it  while  the  system  is  running. 
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The  ticks  parameter  in  a  synchronous  function  specifies  the  number  of 
"ticKs"  between  samples  or  data  transfers.  The  value  of  ticks  is  a 
16-hit  number.  Thus  65,536  discrete  sampling  frequencies  are  possible 
for  each  of  65,536  different  "tick"  rates.  This  provides  a  maximum 
single-channel  sample  rate  of  1  sample  every  100  microseconds 
(possible  in  hardware  but  impractical  in  software)  and  a  minimum  of  1 
sample  every  429,495  seconds.  A  single-channel  rate  greater  than  2KHz 
is  possible,  but  not  recommended.  .    . 

The  figures  below  represent  initial  timing  tests  run  under  RSX-llM. 
It  should  be  noted  that  no  computation  was  performed  on  the  data  other 
than  continuo>^siy  removing  it  from  or  inserting  it  into  the  data 
buffer. 

The  following  data  is  for  the  LPSll  on  a  PDP-11/40  with  memory 
management,  with  no  gain-ranging  option,  and  with  digital  I/O  option. 

Analog  rates: 

1  request  for  1  channel  at  2.5KHz 

1  request  for  2  channels  at  2.0KHz  (aggregate  4KHz) 

2  requests  for  1  channel  at  2.0KHz  (aggregate  4KKz) 
Digital  rates: 

1  request  for  2  channels  at  2.5KHZ  (aggregate  5KH2) 

The  frllowing  data  i-s  for  ♦■he  ARll  on  a  PDP-li/40  with  no  memory 
manacsement,  no  digitai  I/O  option,  r.rtd  no  unipolar  sampling. 

Analog  rates: 

1  request  for  1  channel  at  3.3KHz 

1  request  for  2  channels  at  2.5KHz  (aggregate  5.0KHz) 

2  requests  for  1  channel  at  2.5KHz  (aggregate  5.0KHZ) 
Digital  rate: 

2  requests  for  2  channels  at  3.3KHz  (aggregate  6.6KHz) 


16.6.2   Importance  of  the  I/O  Status  Block 

An  I/O  status  block  must  be  specified  with  every  synchronous  function. 
If  the  first  I/O  status  word  is  nonzero,  the  request  has  been 
terminated  and  the  value  indicates  the  reason  for  termination. 
Otherwise,  the  request  is  in  progress,  and  the  second  I/O  status  word 
contains  the  number  of  data  values  remaining  in  the  buffer  (or  the 
number  of  free  positions  in  the  buffer  for  lO.MDA  and  lO.MDO). 
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If. 6. 3   Buffi 


»nt 


The  buffer  unload  protocol  for  synchronous  input  functions  is 
described  below.  The  user  constructs  a  5-word  block  that  contains  the 
following : 

J  I/O  STATUS  DOUBLE-WORD 

ADDRESS  OF  BUFFER 

ADDRESS  OF  END  OF  BUFFER 

ADDRESS  OF  BUFFER 


lOSB: 

.BLKW 

2 

CURPT: 

.WORD 

BUFFER 

LSTPT: 

.WORD 

BUFFER+n 

PSTPT: 

.WORD 

BUFFER 

Two  of  these  words  are  required  by  the  driver  (T/0  status  block)  and 
the  remaining  three  by  the  user  to  unload  data  values  from  the  buffer. 

The  user  then  issues  the  I/O  request  with  the  appropriate  parameters 
and  the  address  of  the  above  block  as  the  I/O  status  block.  The  QIO 
directive  Os  both  I/O  status  words  to  initialize  them. 

If  the  driver  accepts  the  request,  it  sets  up  a  write  pointer  to  the 
first  word  in  the  user  buffer.  Thus,  the  user  has  a  buffer  read 
pointer  and  the  driver  has  a  buffer  write  pointer.  The  user  and  the 
driver  share  the  second  I/O  status  word,  which  is  the  number  of  data 
words  in  the  buffer  that  contain  data. 

Each  time  the  driver  attempts  to  put  a  sample  value  into  the  buffer, 
it  increments  the  second  I/O  status  word  and  compares  the  result  with 
the  size  of  the  buffer.  If  the  result  is  greater,  buffer  overrun  has 
occurred  and  the  request  is  terminated.  Otherwise,  the  value  is 
stored  in  the  buffer  at  the  address  specified  by  the  driver's  write 
pointer  and  the  write  pointer  is  updated. 

If  the  value  stored  in  the  user  buffer  fills  half  of  the  buffer,  the 
event  flag  specified  in  the  I/O  request  is  set  in  order  to  notify  the 
user  that  a  half  buffer  of  data  is  available  to  be  processed.  Each 
time  the  user  task  is  awakened,  it  should  execute  the  following  code: 


5$: 

CLEF$S 

•  EFN 

lOS: 

TST 

I0SB-*-2 

BEO 

30$ 

MOV 

PCURPT,RO 

DEC 

IOSB+2 

ADD 

#2, CURPT 

CMP 

CURPT, LSTPT 

BLOS 

20$ 

MOV 

FSTPT, CURPT 

20$: 

Process 

data  value 

BR 

10$ 

30$: 

TSTB 

lOSB 

BNE 

40$ 

WTSESS 

»FFN 

BR 

5$ 

; CLEAR  EFN 

;ANY  DATA  IN  BUFFER? 

;IF  EQ  NO 

;GET  NEXT  VALUE  FROM  BUFFER 

; REDUCE  NUMBER  OF  ENTRIES 

; UPDATE  BUFFER  READ  POINTER 

;END  OF  BUFFER? 

;IF  LOS  NO 

.-RESET  BUFFER  READ  POINTER 

;TRY  AGAIN 

.•REQUEST  TERMINATED? 
.•IF  NE  YES 
;WAIT  FOR  EFN 


40$: 


Determine  reason  for  termination 
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for  lO.MDA  and  lO.MDO,  this  protocol  differs  slightly.  The  user  task 
maintains  a  write  pointer  and  the  driver  a  read  pointer.  The  entire 
buffer  nust  be  full  when  the  request  is  executed. 


16.fi. 4  Use  of  A9JLPS  for  Input  and  Output 

The  following  iTORTRAN  example   illustrates   the   proper   protocol   for 
using  ADJLPS  for  synchronous  input  and  output. 

Synchronous  input: 

DIMENSION  IBF(1004) ,IERR(2) ,INTVL(2) 
C 

C  INITIATE  SYNCHRONOUS  A/D  SAMPLING, 
C 

INTVL(l)-2 

INTVL{2)-5 

CALL  RTS(IBF,1004,160,INTVL,IEFN,'i,6,IERR,50,14,15) 
C 

C  INITIALIZC  HALF  BUFFER  INDEX 
C 

INDX-4 
C 

C  WAIT  FOR  HALF  BUFFER  OF  DATA 
C 

10     CALL  WAITFR(IEFN) 
C 

C  CLEAR  EVENT  FLAG 
C 

15     CALL  CLREF(IEFN) 
C 

C  PROCFSS  HALF  BUFFER  OF  DATA 
C 

SUM-0 

DO  20  1-1,500 

SUM-SUM+CVSWG(IBF(I+INDX)) 
2U     CONTINUE 

AVERG-SUM/500 
C 

C  FREE  HALF  BUFFER  FOR  MORE  DATA 
C 

CALL  ADJLPS (IBF, 500) 
C 

C  ADJUST  BUFFER  INDEX 
C 

INDX-INDX-t-500 

IF(INDX.GE.1004)  INDX-4 
C 

C  CHECK  IF  ANOTHER  HALF  BUFFER  OF  DATA  IS  AVAILABLE 
C 

IF(IERR(2) .GE.500  GO  TO  15 

IF(IERR(1) .NE.O)  GO  TO  end  of  sampling 

GO  TO  10 
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Synchronous  output: 

DIMENSION  IBP(1004) ,IERR(2) ,INTVL(2) 
C 

C  FIRST  BUFFER  OF  DATA  MUST  BE  AVAILABLE  AT  START 
C 

C  THIS  EXAMPLE  ASSUMES  FIRST  BUFFER  IS  FULL  AT  START 
C 

C  START  SYNCHRONOUS  DIGITAL  OUTPUT  FUNCTION 
C 

INTVL(1)"2 

INTVL(2)-5 

CALL  SDO(IBF,1004,160,INTVL,IEFN,MASK,IERR,50,14,15) 
C 

C  INITIALIZE  HALF  BUFFER  INDEX 
C 

INDX-4 

e 

C  WAITFOR  ROOM  IN  BUFFER 
C 

10     CALL  WAITER ( I EFN) 
C 

C  CLEAR  EVENT  FLAG 
C 

15     CALL  CLREF(IEFN) 
C 

C  CALCULATE  VALUES  TO  PUT  IN  BUFFER 
C 

X-(Y+2)*Z 

DO  20  1-1,500 

IBP(I+INDX)-X**5/A 
20     CONTINUE 
C 

C  SIGNIFY  ANOTHER  HALF  BUFFER  IS  FULL 
C 

CALL  ADJLPS(IBF,500) 
C 

C  ADJUST  BUFFER  INDEX 
C 

INDX«INOX+500 

IF(INDX.GE.1004)  INDX-4 
C 

C  CHECK  IF  ANOTHER  HALF  BUFFER  IS  EMPTY 
C 

IF(IERR{2) .GE.500)  GO  TO  15 

IF(IERR(1) .NE.O)  GO  TO  end  of  sampling 

GO  TO  10 


NOTE 

In  both  of  the  examples  above,  care  is  taken  to  ensure 
Lhat  the  program  stay  "in  sync"  with  the  driver.  If  the 
program  "loses"  its  position  with  respect  to  the  driver, 
the  function  must  be  stopped  and  restarted,  since  this  is 
the  only  way  to  recover.  Caution  should  be  exercised  to 
ensure  that  the  program  sequence  above  be  used  to  avoid  a 
possible  loss  of  data. 
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F>APBR  TAPB  RBADBR/PUNCH  DRIVERS 


17.1   INTRODUCTION 

The  RSX-llM/M-PLUS  paper  tape  reader/punch  drivers  support  the  PCll 
paper  tape  reader/punch  and  the  PRll  paper  tape  reader.  The  PCll  is  a 
high-speed  reader/punch  capable  of  reading  8-hole,  unoiled,  perforated 
paper  tape  at  300  characters  per  second,  and  punching  tape  at  50 
characters  per  second.  The  PRll  has  the  same  characteristics  as  those 
of  the  paper  tape  reader  portion  of  the  PCll.  All  transfers  are  image 
mode  only,  with  no  interpretation  of  data. 


17.2   GET  LUN  INFORMATION  MACRO 

Word  2  of  the  buffer  filled  by  the  GET  LUN  INFORMATION  system 
directive  (the  first  characteristics  word)  contains  the  following 
information  for  paper  trpe  devices.  A  bit  setting  uf  1  indicates  that 
the  described  characteristic  is  true  for  these  devices. 


Bit   Setting 

1 

0 
0 
0 
0 
0 
0 
0 
0 
0 

10  0 

11  0 


Meaning 

Record-oriented  device 

Carriage-control  device 

Terminal  device 

Pile-structured  device 

Single-directory  device 

Sequential  device 

Mass  storage  device 

User-mode  diagnostics  supported 

Device  supports  22-bit  direct  addressing 

Unit  software  wr ite-locked 

Input  spooled  device 

Output  spooled  device 
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Bit   Setting 


Meaning 


12 

0 

13 

0 

14 

0 

U 

0 

Pseudo  device 

Device  mountable  as  a  communications  channel 
Device  mountable  as  a  FILES-11  volume 
Device  mountable 


Words  3  and  4  of  the  buffer   are   undefined;   word   5   indicates  the 
default  buffer  size,  which  is  64  bytes  for  paper  tape  devices. 


17.3   QIO  MACRO 

Table  17-1  lists  the  standard  functions  of   ths   QIO  macro  that  are 
valid  for  the  paper  tape  reader/punch. 


Table  17-1 
Standard  QIO  Functions  for  the  Paper  Tape  Reader/Punch 


Format 

Function 

QIOSC   10. ATT,... 

QIO$C   lO.DET,... 

QIO$C   lO.KIL,... 

0IO$C   lO.RLB, . . . ,<stadd,size> 

QIO$C   lO.RVB,. . . ,<stadd,size> 

QIO$C   IO.WLB,...,<stadd,size> 

QIO$C   lO.WVB,. . .,<stadd,size> 

Attach  device 

Detach  device 

Cancel  I/O  requests 

READ  logical  block  (reader  only) 

READ  virtual  block  (raader  only) 

WRITE  logical  block  (punch  only) 

WRITE  virtual  block  (punch  only) 

stadd 


The  starcing  address  of   the  data   buffer   (may  be  on  a   byte 
boundary) 


size 


The  data  buffer  size  in  bytes  (must  be  greater  than  0) 

lO.KIL  never  cancels  an  in-progress  read  request.  In»progress  write 
requests  are  canceled  only  when  the  punch  driver  is  waiting  for  the 
punch  to  become  ready  at  the  start  of  a  transfer. 

The  paper  tape  drivers  support  no  device-specific  functions. 
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17.4   STATUS  RETURNS 


Table  17-2  lists  error  and  status  conditions  that  are  returned  by  the 
paper  tape  reader/punch  drivers. 


Table  17-2 
Paper  Tape  Reader/Punch  Status  Returns 


Code 

Reason 

IS. sue 

Successful  completion 

The  operation  specified   In   the   QIO  directive  was 
completed   successfully.    The  second  word  of  the  I/O 
dtatus  block  can  be  examined  to  determine  the   number 
of  bytes  processed.  If  the  operation  involved  reading 
or  writing. 

IS.PND 

I/O  request  pending 

The  operation  specified  in  the  QIO  directive  has   not 
yet   been   executed.    The  I/O  status  block  is  filled 
with  OS. 

IE. ABO 

Operation  aborted 

The  I/O  request  was  cancelled  while   in   progress  or 
while  still  in  the  I/O  queue. 

lE.DAA 

Device  already  attached 

The  physical   device   unit   specified   in   an   10. ATT 
function   was  already   attached  by  the  issuing  task. 
This  code  indicates  that  the  issuing  task  has  already 
attached   the  desired  physical  device  unit,  not  that 
the  unit  was  attached  by  another  task. 

lE.DNA 

Device  not  attached 

The  physical   device   unit   specified   in   an   lO.DET 
function   was  not  attached  by  the  issuing  task.   This 
code  has  no  bearing  on  the  attachment  status  of  other 
tasks. 

lE.DNR 

Device  not  ready 

The  reader  and  punch  drivers  return  this  code  when   a 
time-out  occurs.   The  reader  driver  also  returns  this 
code  when  an  error  condition  (see  Section  17.4.1)   is 
encountered    before   the   initiation   of   the   first 
transfer  after  an  ATTACH  command  has  been  issued. 

IE. EOF 

End-of-file  encountered 

The  reader  driver  encountered  an  error  condition  (see 
Section   17.4.1)   at  a  time  other  than  the  initiation 
of  the  first  read  after  a  valid  ATTACH  command.    The 
second  word  of  the  I/O  status  buffer  contains  a  count 
of  bytes  successfully  read  before  the  error  condition 
was  encountered. 

(continued  on  next  page) 
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T«bl«  17-2   (Cont.) 
Pap«r  Tap*  R«ad«r/Punch  Status  Raturns 


Coda 

Raaaon 

IE. IPC 

Illaqal  function 

^4 

An  lllagal  function  coda  was  spaclfiad   in  an   I/O 
raquast   that   is  not  lagal  for  tha  raspactiva  papar 
tapa  drivars. 

lE.OPL 

Oavica  off  lina 

Tha  physical  davica  unit  associatad  with  tha   LUM 
spaclfiad  in  tha  QIO  diractlva  was  not  on  lina.   Wlian 
the  systea  was  bootad,  a  davica  chack  Indicatad   that 
this   physical   davica   unit   was   not   in   tha 
configuration. 

lE.SPC 

IllAgal  addrass  spaca 

Tha  buffar  spaclfiad  for  a  raad  or  writa  raquast  was 
partially  or  totally  outslda  tha  addrass  spaca  of  thn 
issuing  task.   Altarnativaly,  a  byta  count  of   0  was 
spaclfiad. 

IB.VER 

Unracovaraola  hardware  error  (punch  only) 

The  punch  driver  encountered  an  error  condition   (see 
Section   17.4.1)   at  a  tiae  other  than  the  initiation 
of  a  transfer.   Section  17.4.2  describes  the  action 
of   the  punch  driver   when   an  error  condition  is 
encountered  upon  the  initiation  of  a  transfer. 

17.4.1  Error  Conditions 

There  are  four  error  conditions  that   are   Indistinguishable   to  the 
paper  tape  drivers.   These  conditions  are: 

a  No  tape 

a  Reader  off  line 

a  Power  low 

a  Hardware  Malfunction 


17.4.2  Raady  Racovary 

Whan  the   punch  driver  encounters  an  error  condition   upon 
initiation  of  a  transfer,  the  following  Rtnssage  is  displayed: 

•••  PPn:   ~  NOT  READY 


the 


Tha  unit  nuabar  of  tha  paper  tapa  punch  that  is  not  raady. 
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Thiv  iicssage  is  repeated  every  15  seconds  until  the  error  condition  is 
corrected,  or  until  the  I/O  request  is  canceled.  When  the  error 
condition  has  been  corrected,  the  transfer  will  begin  within  1  second. 


17. S   PROGRAMMING  HINTS 

This  section  contains  information  on  important  programming 
considerations  relevant  to  users  of  the  paper  tape  drivers  described 
in  this  chapter. 


17.5.1   Special  Action  Resulting  from  Attach  and  Detach 

When  an  Attach  or  Detach  is  issued  to  the  punch,  the  punch  driver 
initiates  a  transfer  of  170  (decimal)  nulls.  Upon  the  first  read 
after  an  attach  to  the  reader,  all  nulls  preceding  the  first  non-null 
character  on  the  tape  are  read  and  discarded  by  the  reader  driver. 


17.5.2  Reading  Past  End-of-Tape 

When  the  reader  driver  reads  past  the  physical  end-of-tape,  it 
normally  generatet  at  least  two  incorrect  data  bytes.  These  bytes  are 
included  in  the  byt?  count  returned  by  the  driver.  User  software  that 
does  not  prevent  reids  past  the  physical  end-of-tape  should  discard  at 
least  the  last  six  characters  in  the  buffer  when  IE. EOF  is  returned  by 
the  driver. 
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INDUSTRIAL  CONTROL  SUBSYSTEMS 


18.1   INTRODUCTION 

This  chapter  describes  RSX-llM  drivers  for  two  process  I/O  subsystems: 
the  ICS/ICRll  and  the  DSS/DRSll.  (Driver  support  for  these  I/O 
subsystems  is  not  provided  in  RSX-llM-PLUS  systems.) 

ICSll   and   ICRll   are   local   and  remote   process   I/O   subsystems, 

respectively.    They  operate  under  program  control  as  devices  capable 

of  interrogating  digital  and  analog  input,  and  driving  digital  and 
analog  output. 

DSSll  and  DRSll  are  digital  input  and  output  subsystems,  respectively. 
Under  program  control  they  drive  digital  output  and  interrogate 
digital  input. 


18.1.1  Hardware  Configuration  a 

A  single  ICS  or  ICR  controller  can  handle  up  to  16  I/(»modules  in  any 
configuration;  a  module  contains  If  bits  of  input  or  output  data, 
providing  a  total  of  256  digital  points.  Up  to  12  ICR  or  ICS  units 
are  supported.  The  ICS/ICR  driver  is  tailored  to  the  user's  needs, 
interactively,  through  the  SYSGEN  (System  Generation  program) 
dialogue.  The  driver  is  capable  of  handling  any  combination  of  ICR  or 
ICS  controllers  installed  on  a  single  system. 

The  DSSll  provides  49  optically  isolated  inputs,  including  48 
nonbuffered,  sense-data  inputs  and  one  interrupt  input.  The  DRSll 
provides  48  open-collector,  buffered  outputs  plus  one  interrupt  input, 
'he  DSS/DRS  driver  is  shaped  to  the  user's  system  configuration  in  the 
SYSGEN  dialog.  The  driver  supports  up  to  16  DSSll  and/or  DRSll 
modules. 


18.1.1.1  ICS/ICR  Address  Assignments  -  Each  ICRllA  Unibus  interface 
or  ICSll  file  box  must  be  configured  at  SYSGEN  time  for  individually 
addressable  interrupt  vectors.  Control  and  Status  Registers  (ICSR), 
and  module  Address  Registers  (ICAR),  as  shown  in  Table  18-1. 
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Table  18-1 
ICS/ICR  Address  Assignments 


ICS,  ICR  Unit  Ho. 

Modul*  Addresses 

rcSR/ICAR  Addresses 

Interrupt  Vectors 

0 

171000-171036 

171770-171776 

234-236 

1 

171040-17107« 

171-60-171766 

xxx-xxx-*-2 

2 

171100-17113fi 

171750-171756 

XXX+4-XXX+6 

3 

171140-171176 

171740-171746 

XXX-flO-XXX+12 

4 

171200-171236 

171730-171736 

XXX+14-XXX+16 

5 

171240-171276 

171720-171726 

XXX+20-XXX+22 

6 

171300-171336 

171710-171716 

XXX+24-XXX+26 

7 

171340-171376 

171700-171706 

XXX+30-XXX+32 

10 

171400-171436 

171670-171676 

XXX+34-XXX+36 

11 

171440-171476 

171660-171666 

XXX+40-XXX+42 

12 

171500-171536 

171650-171656 

xxx+44-xxx>46 

13 

171540-171576 

171640-171646 

XXX+50-XXX+52 

NOTES 


nnnnnfi  =«  Control  and  Status  Register 
nnnnn4  ■*  Address  Register 

Additional   controllers   are  assigned 
addresses  above  300. 


vector 


18.1.1.2  DSS/DRS  Address  Assignments  -  Unlike  the  ICS/ICR  subsystem, 
DSS/DRS  devices  are  not  restricted  to  specified  bus  addresses. 
However,  the  following  constraints  apply: 

1.  All  DSSll  modules  must  occupy  a  contiguous  set  of  bus 
addresses. 

2.  All  DRSll  modules  must  occupy  a  contiguous  set  of  bus 
addresses. 

3.  The  total  number  of  DS&ll  and  DRSll  modules  may  not  exceed 
16. 

4.  If  both  module  types  are  installed  in  a  system,  the  DRSll 
must  occupy  the  lower  set  of  bus  and  interrupt-vector 
addresses. 

5.  Bus  request  priority  is  BR4. 
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18.1.1.3   Supported  ICS/ICR  I/O  Modules  -  The  following   modules,   all 
optional,  are  supported  by  the  ICS/ICR  driver: 

D/A  Converters 

lOA-OA  -  4-channel  digital-to-analog  converter 

A/D  Converters 

lAD-IA  -  8-channel   wide-range  differential   analog-to-digital 

converter 
IMX-IA  -   16-channel  flying  capacitor  relay  multiplexer 

Counters 

IDC-IC  -   16-bit  binary  counter 

Bistable  Digital  Outputs 

IDC-OA  -  D/C  flip-flop  driver 

lAC-OA  -  A/C  flip-flop  driver 

IRL-OA  -  Bistable  relay  output 

IRL-OB  -  Flip-flop  relay  output 

Momentary  Digital  Output 

IDC-OB  -  D/C  momentary  driver 
lAC-OE-  -  A/C  momentary  driver 

Digital  Inputs  (Noninterrupting) ^ 

IDC-IA  -  D/C  voltage  sense  Input 
IDC-ID  -  D/C  voltage  input  module 
lAC-IA  -  A/C  voltage  input  module 

Digital  Inputs  (Interrupting) 

IDC-IB  -  D/C  voltage  interrupt  input 
lAC-IB  -  A/C  voltage  interrupt  input 

Terminal  Input/Output 

110  CPS  Remote  Terminal  Interface  to  ICRll 


18.1.2  Alternate  ICSll  Support 

The  ICSll  Industrial  Control  Subsystem   is   supported  either   by   the 

UDCll   or   ICS/ICRll   device   driver.    If  the  system  does  not  have  an 

ICRll  controller,  and  if  a  driver  of  minimum  size   is  required,   then 

UDCll   support   should   be   considered.   The  hardware  requirements  for 
such  support  are  as  follows: 

1.  Each  file  box  must  be  assigned  to  the  same  interrupt  vector 
address  (normally  234). 

2.  The  control  and  status  registe;  within  each  file  box  must 
appear  at  *.he  same  address  within  the  I/O  page  (normally 
171776) . 


1.  Note  that  noninterrupting  input  modules  are  accessed  directly  by  a 
task.  Hence,  while  FORTRAN  interface  routines  are  available,  no 
support  for  such  modules  is  included  in  the  driver. 
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If  support  of  the  lAD-IA  A/D  converter  is  required,  the  following 
module  addressing  and  installation  conventions  are  imposed: 

1.  Each  lAD-IA  converter  and  associated  IMX-IA  relay 
multiplexers  are  assigned  a  fixed  block  of  120  logical 
channel  numbers.  No  more  than  12  lAD-IA  converters  may  be 
installed  in  a  single  system.  Based  on  this  convention,  A/D 
converter  0  occupies  channels  0-119,  A/D  converter  1  occupies 
120-239,  and  so  forth. 

2.  Regardless  of  the  actual  number  of  IMX-IA  multiplexers 
installed,  each  converter  preempts  a  block  of  eight 
contiguous  module  slots. 

3.  The  slots  reserved  for  all  A/D  converters  and  multiplexers 
must  occupy  a  block  of  contiguous  module  slots. 

If  necessary,  Field  Service  personnel  can  make  the  vector  and  address 
changes.  Assuming  the  hardware  configuration  is  correct,  the  user  can 
implement  the  desired  UDCll  software  support  by  answering  in  the 
affirmative  all  SYSGEN  questions  relating  to  the  UDCll. 

If  tht  additional  ICS/ICR-11  driver  features  are  required  (at  a 
commensurate  increase  in  the  memory  requi reiients)  ,  then  each  ICSll 
file  box  must  be  configured  for  individually  addressable  interrupt 
vectors  and  control  status  registers.  This  change  can  be  performed  by 
Field  Service  personnel.  The  necessary  software  support  is 
incorporated  by  answering  in  the  affirmative  all  SYSGEN  questions 
relating  to  the  ICS/ICRll. 

The  additional  ICSll  capabilities  provided  by  the  .JS/ICRll  driver  may 
be  summarized  as  follows: 

1.  Multicontroller ,  parallel  operation 

2.  Increased  A/D  conversion  throughput 

3.  Activation  of  tasks  directly  from  digital  interrupts  or 
counters 

4.  No  requirement  to  install  modules  of  the  same  type  in 
contiguous  slots 

Section  18.7  summarizes  the  software  differences  between  tho  UDC  and 
ICS/ICR  drivers  in  detail. 


18.1.3   Software  Suppo  *• 

Both  ICS/ICR  and  DSS/DRS  operations  are  divided  into  two  categories: 

1.  Functions  performed  directly  by  any  task 

2.  Functions  requiring  driver  services 

Direct  functions  ace  accomplished  through  memory  references  to  the 
ICS/ICR  or  DSS/DRS  registers  on  the  I/O  page.  In  a  protected  system 
any  task  nay  gain  restricted  access  to  the  device  registers  by  linking 
to  a  global  common  block  that  resides  within  the  appropriate  physical 
memory  limits..,   Direct  functions  consist  of: 

1.  Reading   counter   modules 

2.  Reading   any  digital    input   module    (DSS) 
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NOTE 

All  functions  listed  in  '.his  subsection 
apply  to  ICS/ICR  modules.  Those  which 
also  apply  to  the  D:;s  and/or  DRS 
subsystems  are  so  marked. 

Driver  requests  are  divided  into  the  following  categories: 

1.  Noninterrupt ing  output  functions 

a.  Bistable  (flip-flop)  digital  output  (DRS) 

b.  Analog  output 

c.  Momentary  (single-shot)  digital  output 

2.  Requests  for  interrupting  functions 

a.  Analog  input 

b.  Remote  terminal  output 

3.  Requests  for  unsolicited  interrupts 

a.  Digital  interrupts  (OSS/DRS) 

b.  Counter  interrupts 

c.  Remote  terminal  input 

d.  Remote  unit  or  serial  line  errors 

With  the  exception  of  A/D  input  and  remote  terminal  output,  all 
functions  are  complete  upon  return  to  the  user's  task. 

Under  RSX-llM,  noninterrupting  output  functions  are  immediately 
submitted  to  the  controller  through  a  circular  buffer  that  is  filled 
at  driver  level  and  emptied  at  interrupt  level.  A  QIC  is  considered 
successfully  completed  when  the  request  is  inserted  in  the  circular 
buffer . 

The  following  operations  are  in  this  category: 

1.  Bistable  digital  outputs 

2.  Analog  outputs 

3.  Momentary  digital  outputs 

Interrupting  functions  are  those  operations  that  generate  an  interrupt 
within  some  fixed  time  after  initiation.  The  driver  allows  a  list  of 
multiple  transactions  to  be  specified  in  a  single  QIC.  Each 
transaction  is  initiated  in  sequence  without  waiting  for  the  preceding 
interrupt,  until  either  the  list  is  exhausted  or  all  modules  of  the 
specified  type  are  active.  The  following  operations  are  in  this 
category: 

1.  A/D  inputs 

2.  Remote  terminal  output 
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Unsolicited  Interrupts  may  require  no  Initiation  by  the  processor  and 
occur  at  Indeterminate  intervals.  The  following  functions  are  In  this 
category: 

1.  Interrupting  digital  Inputs  (DSS/DRS) 

2.  Counter  modules 

3.  Remote  terminal  Input 

4.  Error  Interrupts 

All  unsolicited  Interrupt  data,  except  for  errors,  may  be  placed  In  a 
task-provided  circular  buffer.  On  Interrupt,  an  event  flag  specified 
by  the  task  Is  set.  Such  data  for  each  module  type  Is  supplied  to 
only  one  task  per  controller.  In  addition,  the  driver  will  activate 
selected  tasks  on  the  occurrence  of  digital  or  terminal  input 
Interrupts. 

Error  interrupts  are  described  later  In  this  chapter. 

Terminal  support  is  restricted  to  parsing  terminal  data  between  the 
device  and  a  task.  The  only  special  character  is  Control-C  (003), 
which  may  cause  a  user-specified  task  to  he  made  active.  There  is  no 
other  special  processing  for  terminal  I/O  except  that  the  parity  bit 
is  removed.  This  Is  similar  to  the  terminal  driver  function  of 
lO.RAL. 

1.  MCR  is  not  Invoked. 

2.  Characters  are  not  echoed. 

3.  Carriage  control  is  not  performed. 

4.  TABS,  RUEtOUTs,  and  so  forth  are  not  recognized. 

5.  Line  terminators  are  not  recognized. 

6.  Fill  characters  are  not  generated. 


18.1.4  UDCll  Software  Compatibility 

Many  of  the  MACRO  and  FORTRAN  interfaces  described  in  the  following 
paragraphs  are  fully  compatible  with  existing  UDCll  applications 
software;  however,  the  user  should  consult  Section  18.7  for  a  summary 
of  differences  that  do  exist  between  UDC  and  ICS/ICR  software. 


18.1.5  Module  Addressing  Conventions 

Table  18-2  Illustrates  the  relationship  between  physical  slot  numbers, 
bus  addresses  and  relative  addresses  for  a  given  ICS/ICR 
configuration.   It  Is  referred  to  in  the  following  discussion. 

Each  A/D  converter  is  assigned  a  block  of  120  channels.  The  number  of 
channels  in  use  within  the  block  depends  on  the  number  of  multiplexers 
installed.  Specifically,  each  A/D  converter  has  eight  channels,  and 
each  associated  multiplexer  has  16. 
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Table  18-2 
Sample  ICS/ICR  Configuration 


Unit: 

0 

Modnle 

Slot 

Number 

Number 

Type 

Bus  Address 

Relative  Addresses 

0. 

9. 

D/A  converter 

171000 

0-3. 

1. 

10. 

A/D  converter 

171002 

0-119. 

2. 

11. 

A/D  multiplexer 

3. 

12. 

Counter 

171006 

0 

4. 

13. 

Flip-flop  (Jriver 

171010 

0-15. 

5. 

14. 

D/A  converter 

171012 

4-7. 

6. 

15. 

Fl Ip-f lop  driver 

171014 

16.-31. 

7. 

16. 

Counter 

171016 

1. 

8. 

17. 

A/D  converter 

171020 

120.-239. 

As  noted,  a  block  of  120  relative  addresses  is  reserved  for  each  A/D 
converter.  The  converter  and  multiplexer  in  slots  10  and  11  contain 
channels  0  through  23.  The  converter  in  slot  17  contains  channels  120 
through  127.  An  attempt  to  access  a  nonexistent  channel  (for  example, 
channel  30  or  channel  129)  will  be  rejected  by  the  driver. 

The  user  should  observe  that  the  bistable  drivers  in  slots  13  and  15 
contain  relative  point  numbers  0  through  15,  and  16  through  29 
although  the  modules  are  not  physically  adjacent.  In  general,  the 
relationship  between  slot  number,  module  type,  bus  address,  and 
relative  address  is  as  follows: 


1.  A  set  of  contiguous  relative  addresses  is  defined  for  each 
module  of  a  given  type  that  is  installed.  Each  relative 
address,  when  qualified  by  type,  uniquely  identifies  a 
digital  point  or  channel. 

2.  A  set  of  slot  numbers  and  bus  addresses,  possibly  not 
contiguous,  is  occupied  by  all  modules  of  a  given  type.  Such 
addresses  may  be  assigned  solely  on  the  basis  of  hardware  and 
installation  considerations.  Increasing  relative  addresses 
correspond  to  increasing  bus  addresses. 


Table  lS-3  is  an  example  of  the 
interrupt  points,  and  point 
configuration. 


relationship 
numbers   for 


among   bus   addresses, 
a   sample   DSSll/DRSll 


Table  18-3 
Sample  DSS/DRS  Configuration 


Bus  Addresses 

Module  Type 

Po  i  n  t  s 

Interrupt  Point 

160030-160036 
160040-160046 

170010-170016 
170020-170026 

DRSll 
DRSll 

DSSll 
DSSll 

0-47. 
48.-95. 

0-47. 
48.-95. 

0 

1 

2 

3 
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All  addrsssing  is  by  point  number.  Except  for  the  interrupts,  all 
points  are  numbered  sequentially  by  type  (DSS  or  DRS) ,  starting  with 
the  first  point  on  the  lowest  address  assigned  to  a  given  module  type. 
Interrupt  points  are  defined  by  means  of  a  Ifi-bit  mask  word.  Each  bit 
in  the  mask  defines  an  interrupting  module;  high-order  bits 
correspond  to  increasing  bus  addresses. 


18.2   LUN  INFORMATION 


A   request   for   logical   unit   information   returns    the 
device-dependent  data  in  words  2  through  5  of  the  buffer; 

WD  02  -  0 

WD  03  -  Undefined 

WD  04  -  Undefined 

WD  05  -  0 


18.3   ASSEMBLY  LANGUAGE  INTERFACE 


following 


Table  18-4  summarizes  standard  and  device-specific  QIO  functions 
supf>orted  by  the  ICS/ICR  driver.  Only  the  five  functions  indicated  by 
a  footnote  are  supported  by  the  DSS/DRS  driver. 


Table  18-4 
Summary  of  Industrial  Control  QIO  Functions 


Format 

Function 

QIOSC 

IO.CCI,...,<stadd,slzb,tevf> 

CONNECT  a  buffer  to 
digital  interrupts 

PIOSC 

lO.CTI, . . . ,<stadd,sizb,tevf , 
arv> 

CONNECT  a  buffer  to 
counter  interrupts 

oiosc 

lO.CTY, . . . ,<stadd,sizb,tevf> 

CONNECT  a  buffer  to 
terminal  interrupts 

oiosc 

lO.DCI,. .. 

Disconnect  a  buffer  f 
di  ital  interrupts 

rom 

OIOSC 

10. DTI,... 

Disconnect  a  buffer  f 
counter  interrupts 

rom 

OIOSC 

lO.DTY,... 

Disconnect  a  buffer  f 
terminal  interrupts 

rom 

OIOSC 

lO.FLN, ... 

Set  controller  off  li 

ne 

OIOSC 

IO.ITI,...,<mn,ic> 

INITIALIZE  a  counter 

OIOSC 

lO.LDI, . . . ,<tname, f ,tevf 1 , 
pn,csm>l 

LINK  task  to  digital 
interrupts 

OIOSC 

lO.LKE, . . . ,<tname, [ ,tevf ) > 

LINK  task  to  error 
interrupts 

(continued  on  next  page) 
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Table  18-4   (Cont.) 
Summary  of  Industrial  Control  010  Functions 


Format 

Function 

oiosc 

lO.LTI, . .. ,<tname, f »tevf] 
cn( ,arvl > 

LINK  task  to  counter 
interrupts 

QXO$C 

IO.LTY,...,<tnam*, [,tevf)> 

LINK  task  to  remote 
terminal  interrupts 

OIOSC 

lO.MLO, . . . ,<opn,pp,dp>l 

OPEN  or  close  bistable 
digital  output  points 

OIOSC 

lO.MSO, . . . ,<opn,dp> 

PULSE  momentary  digital 
output  points 

OIOSC 

lO.NLK, .. . ,<tname>l 

UNLINK  a  task  from  all 
Interrupts 

OIOSC 

lO.ONL,... 

Place  ICS/ICR  controller 
onl ine 

OIOSC 

10. RAD, . ..,<stadd>l 

READ  activating  data 

OIOSC 

lO.RBC, . . . ,<stadd,size, 
stcnta> 

INITIATE  multiple  A/D 
conversions 

OIOSC 

10. SAO, . . . ,<chn,vout> 

PERFORM  analog  output 

OIOSC 

lO.UDI , . . . ,<tname>l 

UNLINK  a  task  from 
digital  interrupts 

OIOSC 

lO.UER, . . . ,<tname> 

UNLINK  a  task  from  error 
interrupts 

OIOSC 

IO.UTI,...,<tname> 

UNLINK  a   task  from 
counter  interrupts 

OIOSC 

lO.UTY, . . . ,<tname> 

UNLINK  a  task  from 
terminal  Interrupts. 

OIOSC 

lO.WLB, . . . ,<stadd,sizb> 

TRANSMIT  data  to  the  ICR 
remote  terminal 

1.  These  functions  are  supported  by  the  DSS/DRS  driver. 


arv 


chn 


en 


The  starting  address  of  a   buffer   containing   initial   or   reset 
counter  values.   The  buffer  must  be  aligned  on  a  word  boundary. 


The  D/A  channel  number. 


The  counter  number. 
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can 

The  change-of-state  mask. 

dp 

The  binary  data  pattern. 

ic 

The  Initial  count. 

■in 

The  module  number. 

opn 

The  first  bistable  (latching)  digital  output  point  number.    This 
value  must  be  on  a  module  boundary  (evenly  divisible  by  16). 

pn 

The  point  number  (must  be  assigned  on  a  module  boundary). 

PP 

A  16-blt  mask. 


sisb 


The  data  buffer  size  in  bytes.  For  a  circular  buffer  connected 
to  unsolicited  interrupts,  this  value  must  be  even  and  large 
enough  to  include  one  entry  plus  the  2-word  header. 


sise 


The  data  and  control  buffer  size  in  bytes.   This  value  must  be  an 
even  nunber  that  is  greater  than  0. 


stadd 


The  starting  address  of  the  data   buffer   (must  be  on  a   word 
boundary) . 


Btaddb 


The  starting  address  of   the   t«»rminal   output  buffer   (may  be 
aligned  on  a  byte  boundary). 
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■tcnta 


The  start'  ,  address  of  the  control  buffer  (must  be  on  a  word 
boundary) ;  each  control  buffer  word  must  be  constructed  as 
described  in  Table  18-5  (Section  18.3.2). 


tevf 


An  event  flag  number  In  the  range  0  to  96,  (If  the  group-global 
event  flag  SYSGEN  opt'on  was  selected),  or  0  to  64  If 
group-global  event  flags  are  noc  supported. 


tnane 


A  task  name  composed  of  1  to  6  alphanumeric  characters  in  a 
2-word  RADIX-50  format.  Two  arguments,  each  containing  three 
characters,  are  required  for  this  parameter.  For  example,  the 
task  name  ICNAME  is  specified  as: 

C^RICNf^RAME,...) 

If  the  task  name  is  less  than  four  characters,  a  null  argument 
must  be  specified  as  follows  for  task  ABC: 

K,    RABC  ,  ,  .  .  ]t  ^ 

vout 

A  binary  number  between  0  and  1023.  that  is  to  be  converted  to 
an  analov.  output. 

The  following  sections  contain  a  detailed  description  of  each 
function.  In  the  discussion  of  QIO  request  parameters,  the  following 
conventions  apply. 

All  numbering  is  relative. 

Module  numbers  start  at  0  beginning  with  the  first  module  of  a  given 
type.  Increasing  module  numbers  correspond  to  increasing  physio^l  bus 
addresses. 

Channel  numbers  start  at  0,  with  channel  0  as  the  first  channel  on  the 
first  module  of  a  given  type. 

Point  numbers  start  at  0  with  point  0  as  the  first  point  on  the  first 
module  of  a  given  type.  Points  within  a  module  are  numbered  "from 
right  to  left"  in  increasing  order. 

It  should  be  remembered  that  there  is  no  requirement  for  ICS/ICR 
modules  of  a  given  type  to  occupy  contiguous  slots;  thus,  for 
example,  digital  points  ''5(10)  and  16(10)  need  not  reside  on 
physically  adjccent  modules.  This  restriction  does  apply  to  DSS/DRS 
modules,  however. 
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It  is  aasunad  that  the  number  of  points  or  channels  per  module  <s  a 
constant  for  each  generic  type.  Specifically,  the  following  weights 
apply: 

1.  Bach  ICS/ICR  Digital  I/O  Module  contains  If  points. 

2.  Each  DSS/DRS  Digital  I/O  Module  contains  48  points. 

3.  Each.  Counter  Module  contains  1  ch?innel. 

4.  Each  D/A  Module  contains  4  channels. 

5.  Each  A/D  Converter  contains  120  channels. 

As  stated  above,  an  A/D  converter  is  assigned  a  block  of  120  channels. 
The  number  of  channels  in  use  within  the  block  depends  on  the  number 
of  multiplexers  installed.  The  driver  will  reject  an  attempt  to 
address  a  nonexistent  channel. 


18.3.1  General  Error  Status  Returns 

The  system  recognizes  and  handles  two  kinds  of  status  conditions   when 
they  occur  in  I/O  requests: 

•  Directive   conditions,   which   indicate   the   acceptance   or 
rejection  of  the  QIO  directive  itself 

•  I/O  status  conditions,  which  indicate  the  success  or   failure 
of  the  I/O  operation 

Table  18-7   lists   numsrlcal   values   of   returns   for   both   assembly 
language  and  FORTRAN  interfaces. 

The  following  directive  and  I/O  status  returns  apply  uniformly  to   all 
requests. 


18.3.1.1   Directive  Conditions 

IS. sue  -  Directive  accepted.   The  first   six   parameters   of   the  010 

directive  were   valid,   and   sufficient   dynamic   memory  was 

available  to   allocate   an   I/O   packet.    The   directive  Is 
accepted . 

lE.ADP  -  Invalid  address.  The  I/O  status  block  or  the  QIO  DPB  was 
outside  of  the  issuing  task's  address  space  or  was  not 
aligned  on  a  word  boundary. 

lE.IEP  -  Invalid  event  flag  number. 

lE.ILU  -  Invalid  logical  unit  number.   The  lun  specification  in  a   QIO 

directive   was   invalid   for   the  issuing  task.   For  example, 

there  were  only  five  logical  unit  numbers  associated  with  the 

task,  and  the  value  specified  for  lun  was  greater  than  five. 


# 
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IE. NOD  -  Insufficient  dyn«w!c  n«nory.  There  wan  not  enough  dynamic 
nemory  to  allocate  an  I/O  packet  for  the  I/O  request.  The 
user  can  try  again  later  by  blocking  the  task  with  a  WAITPOR 
SIGNIFICANT  EVrNT  directive.  Note  that  WAITFOR  SIGNIFICANT 
EVENT  is  the  only  effective  way  for  the  issuing  task  to  block 
its  execution,  since  other  directives  that  could  be  used  for 
this  purpose  themselves  require  dynamic  memory  for  their 
execution  (for  example,  MARK  TIME). 

lE.SDP  -  Invalid  Die  number  or  DPB  size.  The  directive  identification 
code  (DIC)  or  the  size  of  the  directive  parameter  block  (DPB) 
was  incorrect;  the  legal  range  for  a  DIC  is  from  I  through 
127,  and  all  DIC  values  must  be  odd.  Each  individual 
directive  requires  a  DPB  of  a  certain  size.  If  the  size  Is 
not  correct  for  the  particular  directive,  this  code  is 
returned . 

lE.ULN  -  Unassigned  LUN.  The  logical  unit  number  in  the  QIC  directive 
was  not  associated  with  a  physical  device  unit.  The  user  may 
recover  from  this  error  by  issuing  a  valid  Assign  LUN 
directive  and  then  reissuing  the  rejected  directive. 


18.3.1.2   I/O  Conditions 

IE. ABO  -  Operation  aborted.  Thp  specified  operation  was  canceled  by 
lO.KIL  or  the  request  timed  out  while  the  unit  was  off  line. 

lE.OFL  -  Controller  off  line.  The  physical  device  unit  associated 
with  the  LUN  specified  in  the  (}I0  directive  was  not  on  line. 
An  iCS/ICR  controller  may  be  off  line  because  a  device  check 
during  bootstrap  load  has  indicated  that  the  controller  is 
not  in  the  configuration. 

lE.DNR  -  Controller  not  ready.  A  nonrecoverable  controller  error  has 
been  detected. 

lE.IFC  -  Illegal  function.   A  function  code  was   included   in   an  I/O 

request   that   is   illegal  for  the  ICS/ICR.   The  function  may 

also  refer  to  an  ICS/ICR  module  type  or  function  that  was  not 
specified  during  system  generation. 


18.3.2  A/D  Input  -  Read  Multiple  A/D  Channels 

This  function  provides  the  capability  of  reading  several  A/D  channels 
at  any  permissible  gain.  The  driver  is  capable  of  initiating  parallel 
transfers  when  more  than  one  A/D  converter  Is  installed  ir  a  file  box; 
however,  only  one  interrupt  module  request  (remote  terminal  or  A/D) 
may  be  in  progress  at  a  given  time. 

QIO  DPB  format: 

QIOSC  lO.RBC, . . . ,<stadd ,size,stcnta> 
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■tadd 

The  starting  address  of  the  «lata  buffer   (must  be  en  a  word 
boundary) . 


sis* 


The  data  buffer  siie  in  bytes  (must  be  even  and  greater  than  0)| 
the  control  buffer  is  the  same  siie. 


•tcnta 


The  starting  address  of  the  control  buffer  (must  be  on  a  word 
boundary) ;  each  control  buffer  word  must  be  constructed  as  shown 
in  Table  18-5. 


Return  Status: 

IS. sue  -  Function  successfully  completed. 

IE. BAD  -  Illegal  channel  or  gain  code  specified. 

IE. BYT  -  Data  buffer  is  byte  aligned.   Alternatively,  the   length 
of  the  buffer  is  not  an  even  number  of  bytes. 

lE.DNR  -  Device  not   ready.    A/D  converter   interrupt   time-out 
occurred . 

Note  that  the  second  I/O  status  word   contains   a   count   of   the 
number  of  conversions  successfully  completed. 

One  control  word  is  paired  with  each  data  word.  That  is,  the  data 
appearing  in  a  data  array  element  is  obtained  using  the  gain  and 
channel  number  specified  in  the  corresponding  element  of  the  control 
array.  Control  words  specify  the  gain  and  channel  in  the  format  shown 
in  Table  18-5. 

Upon  receiving  and  validating  the  parameters  within  the  I/O  packet, 
the  driver  will  initiate  the  following  sampling  procedure: 

1.  The  control  word  is  fetched  and  tested  for  validity  (that  is, 
fot  Icjal  gain  and  channel).  If  an  error  is  encountered  or 
no  further  control  words  remain,  processing  is  terminated  as 
described  in  Step  4. 

2.  Assuming  the  A/D  converter  board  is  idle,  the  driver  starts 
the  conversion,  sets  this  resource  busy,  and  returns  to  step 
1.  If  the  converter  is  busy,  the  driver  returns  control  to 
the  system  after  saving  the  data  required  to  initiate  the 
conversion  when  the  channel  becomes  idle. 

3.  On  the  occurrence  of  an  A/D  interrupt,  the  interrupt  service 
routine  initiates  the  appropriate  processing  at  the  non 
interrupt  level  that  will  either  set  the  channel  idle  or 
initiate  a  previous  request  stored  during  step  2.  The 
occurrence  of  the  latter  results  in  processing  of  additional 
control  words  as  described  in  step  1. 


18-14 


INDUSTRIAL  CONTROL  SUBSYSTEMS 


Tabl*  18-5 
A/D  Conversion  Control  Word 


Bits 


0-11 
12-15 


Meaning 


Channel  Nunber  range: 

Gain  value  for 
this  sample.   The 
binary  value  is 
as  follows: 

iS   14   n   12 


0-1919 
Gain 


4.   The  converted  value 
in  a  Ifi-bit  word,  wi 


0 

0 

1 

0 

0 

2 

0 

illegal 

0 

illegal 

1 

10 

1 

20 

1 

Illegal 

1 

illegal 

0 

50 

0 

100 

0 

illegal 

0 

illegal 

1 

0 

200 

1 

0 

1000 

1 

illegal 

1 

illegal 

s  returned  as  12   bits,   lef t- justi f ied, 
h  the  low-order  4  bits  set  to  0. 


5.   A/D  requests   are   terminated   under   any  of   the   following 
conditions : 

a.  All  control  words  have  been  processed. 

b.  A  hardware  error  has  occurred. 

c.  An  error  in  a  control  word  has  been  detected. 

Regardless  of  the  cause,  the  driver  cannot  complete  request  processing 
until  all  pending  A/D  transfers  have  gone  to  completion. 

Because  of  overlapped  processing,  multiple  errors  can  occur  (for 
example,  a  hardware  error  and  an  erroneous  control  word) .  The  driver 
returns  the  status  associated  with  the  earliest  transaction  that 
caused  an  error  condition.  Thus,  at  the  user  interface,  the  driver 
appears  to  execute  all  conversions  sequentially. 


18.3.3  Analog  Output 

This  function  provides  the  capability  of   setting  a   single  analog 
output  channel  to  a  specified  voltage. 
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QIO  DPB  format: 

OIOSC  lO.SAO, . . . ,<chn,vout> 

chn 

Th*  output  channel  number. 

vout 

The  output  voltage  representation. 

Output  voltage  varies  linearly  with  the  binary  input  to  the  channel, 
where  0  to  plus  10  volts  (+10v.)  is  represented  by  integers  from  0  to 
1023. 

Return  Status: 

IS. sue  -  Function  submitted  for  output  to  controller. 

IE. MOD  -  Nonexistent  D/A  channel  was  specified. 
The  second  I/O  status  word  is  0. 

18.3.4  Momentary  Digital  Output  -  Multi-Point 

This  function  provides  the  capability  of  pulsing  a  field  of  up  to  16 
momentary  (single-shot)  digital  output  points.  Fields  must  be  aligned 
on  module  boundaries. 

QIO  DPB  format: 

0IO$C  lO.MSO, . . . ,<opn,dp> 


opn 


dp 


The  starting  digital  output  point  number.   Point  number   must   be 
aligned  on  a  module  boundary  (that  is,  must  be  a  multiple  of  16). 


The  16-bit  mask.   One  point  is  pulsed  corresponding  to   each   bit 
set  in  the  mask  word. 


Return  Status: 

IS. sue  -  Function  submitted  for  output  to  the  controller. 

IE. MOD  -  Invalid   starting  point   number   specified.    Point   is 

nonexistent  or  not  aligned  on  a  module  boundary. 
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IS.:".  5   Blstabl*  Digital  Output  -  Multi-Point 

This  cunctlon  provides  the  capability  of  setting  or  resetting  a  field 
of  up  to  lf>  bistable  digital  output  points.  Fields  must  be  aligned  on 
a  module  boundary. 

QIO  DPB  format: 

OIOSC  lO.MLO, . . . ,<opn,pp,dp> 


The  starting  digital  output  point  number.   Point  number  must   be 
aligned  on  a  module  boundary  (that  Is,  must  be  a  multiple  of  lf>)  , 


The  16-blt  mask. 


«» 


The  data  pattern. 


A  bit  is  set  in  the  mask  word  for  each  point  that  may  change  state. 
The  state  of  points  corresponding  to  reset  mask  bits  is  unaltered. 
When  tht  mask  bit  is  set,  the  output  is  "closed"  If  the  data  bit  is 
set  and  "open"  if  the  data  bit  is  clear. 

Return  Status: 

IS. sue  -  Function  submitted  for  output  to  the  controller. 

IE. MOD  -  Invalid  starting  point  number  specified.   Point  does  not 
exist  or  is  not  aligned  on  a  module  boundary. 


18.3.^  Unsolicited  Interrupt  Processing 
Unsolicited  interrupts  consist  of  the  following: 

1.  Digital  interrupts 

2.  Counter  interrupts 

3.  Remote  terminal  input 

4.  Hardware  errors 

Based  on  the   type   of   Interrupt,   the  driver  may  dispose  of   the 
interrupt  data  in  one  or  more  of  the  following  ways: 

1.  The  d-  1  may  be  furnished  to  a  ta5?k  that  has  Issued  a  request 
to  mo  cor  such  information  continually.  This  alternative  is 
not  available  in  t.»   DSS/DRS  driver. 

2.  A  task  may  be  activated  by  a  specific  input.  That  Is,  a 
dormant  task  can  be  requested  to  run,  or  an  event  flag  may  be 
set  if  the  task  is  currently  active. 
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Th«  driver  will  allow  continual  monitoring  for  digital,  counter,  and 
terminal  inputs  with  the  provision  that,  for  each  controller,  only  one 
task  per  module  type  may  receive  such  inputs. 

Task  activation  is  permitted  for  digital,  terminal,  and  error 
Interrupts.  The  processing  related  to  hardware  errors  is  discussed  in 
Section  18.5.  Activation  of  tasks  by  digital,  counter,  and  terminal 
inputs  is  covered  in  Section  18.9.7. 

The  driver  functions  described  in  the  following  paragraphs  allow  a 
task  to  continually  receive  interrupt  data.  To  monitor  such  data,  a 
task  must  'provide: 

1.  A  buffer  that  is  filled  by  the  driver   .J  emptied  by  the  task 
in  circular  fashion 

2.  An  event  flag  that  will  be  set  upon  the   occurrence   of   each 
interrupt 

The  driver  will  connect  a  single  task  per  controller  to  receive 
interrupts  from  a  specific  module  type. 

The  buffer  to  be  connected  has  the  format  shown  below: 


FORTRAN 

Index 

Contents 

1 

driver  index 

2 

user  index 

3 

word  0  of  entry 

4 

word  1  of  entry 

The  buffer  consists  of  a  2-word  header  containing  the  driver  and  user 
index,  aas  shown,  followed  by  a  data  area  that  is  subdivided  into 
fixed-length  entries.  Each  entry  consists  of  a  word  containing  the 
entry  existence  indicator  followed  by  one  or  more  words  of 
device-dependent  data.  Such  information  usually  consists  of  module 
data,  relative  module  number,  and  a  code  Identifying  a  module  type. 
On  the  occurrence  of  an  Interrupt,  the  diiver  enters  data  in  the 
location  currently  indicated  by  the  driver  index.  This  index  can  be 
considered  as  a  FORTRAN  index  into  thf  buffer.  That  is,  the  first 
location  in  the  buffer  is  associated  with  the  index  1.  The  beginning 
of  the  dat2  area  is  associated  with  the  first  entry,  index  3.  Entries 
are  made  in  a  circular  fashion  starting  at  the  beginning  of  the  data 
area,  filling  in  order  of  increasing  memory  address,  and  wrapping 
around  to  the  beginning  of  the  data  area  when  thei.  is  insufficient 
space  for  an  entry  at  the  end.  Note  that  the  size  of  the  data  area 
must  be  an  integer  multiple  of  the  entry  size. 

It  is  expected  tha^  the  connected  task  will  maintain  the  user  index, 
ensurii.g  that  it  indicate  where,  in  the  buffer,  the  task  is  to  process 
interrupt  data  next. 

Whe.i  the  task  is  activated  by  the  driver,  it  should   process   data  in 

the   buffer   starting   at   the   location  indicated  by  its  pointer,  and 

continuing  in  circular  fashion  until  an  existence  indicator  is 
encountered  that  is  0. 
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The  •xistance  indicator  is  set  to  *\  when  a  buffer  entry  is  made. 
Except  to  record  a  hardware  error,  the  contents  of  an  entry  are  not 
altered  by  the  driver  if  the  indicator  is  nonzero.  Hence,  when  a 
requester  has  revoved  or  processed  the  entry,  he  must  clear  the 
existence  indicator  in  order  to  free  the  buffer  entry  position.  If 
the  driver  detects  a  nonzero  indicator,  (that  is,  data  input  has 
occurred  in  a  burst  sufficient  to  overrun  the  buffer),  the  data  is 
discarded  and  a  count  of  data  overruns  is  incremented.  The  count  is 
maintained  in  the  entry  existence  indicator,  which,  as  noted  above,  is 
set  to  *-\  to  indicate  nu  overruns  between  entries,  -•■2  to  indicate  a 
hardware  error  entry,  or  a  negative  value  recording  the  two's 
complement  of  the  number  of  times  data  has  been  discarded  between 
entries.  The  overrun  count  will  never  be  allowed  to  wrap  around  to  a 
positive  value. 

In  the  event  of  a  nonrecoverable  controller  error  (remote  unit 
power-fail  or  hard  data  error/  all  connected  tasks  are  activated  with 
the  following  entry  in  the  circular  buffer: 

WD  00  Hardware  error  indicator  (♦2) 


WD  nn  Contents  of  ICSR  register 

WD  nn-fl         Physical  unit  number 
WD  nn'f2         Generic  code  indicator 
set  to  177770(8) 


nn 


The  offset  to  module  data  word, 


This  entry  is  always  placed   in   the   buffer   regardless   of   overflow 
status . 

The  error  flags  are  obtained  from  the  controller  ICSR  word  at  the  time 
the  error  was  detected  (see  Table  18-7). 


18.3.6.1  Connect  to  Digital  Interrupts  -  This   function   allows   a 
single  task  to  receive  digital  interrupt  data. 

QIO  DPB  format: 

QIO  lO.CCI, . . . ,<stadd,slzb,tevf > 


stadd 


The  starting  address  of  buffer  to   be   connected   (must   be   word 
aligned)  . 


slzb 


tevf 


The  length  of  buffer  in  bytes  (must   be   even) .    Minimum   buffer 
length  is  14  bytes. 


The  trigger  evsnt  flag  number. 
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Return  Statusi 


IS. sue  -  Function  successfully  completed.  Second  I/O  status  word 
contains  the  number  of  words  passed  per  interrupt  in  the 
low  byte,  and  the  initial  FORTRAN  index  in  the  high 
byte. 

IE. BYT  -  Buffer  address  is  byte  aligned  or  length  is  an  odd 
number  of  bytes. 

IE, CON  -  Interrupt  already  connected  to  another  task. 

lE.IBF  -  Invalid  event  flag  number. 

lE.PRI  -  Task  checkpointable  and  not  fixed  in  memory. 

lE.SPC  -  Interrupt  circular  buffer   was   not   wholly  within   the 
.  address   space   of   the  task.   Alternatively,  the  buffer 

»  was  too  small  for   a   single   data   entry   (seven   words 

' -f-        minimum)  . 

Entry  Format: 

WD  00  -  Existence  Indicator 

WD  01  -  Change  of  state  indicator 

WD  0?  -  Module  data 

WD  03  -  Relative  module  number 

WD  04  -  Generic  Code  1,  2,   or  3,  indicating  a  digital  interrupt 

The  contents  of  the  existence  indicator  have  be tn  described 
previously. 

The  change-of-state  indicator  records  those  bits  for  which  a  change  of 
state  in  the  direction  of  interest  has  been  detected.  The  direction 
of  the  change  lay  be  from  0  to  1  (point  closed  (PCL))  or  1  to  0  (point 
open  (POP))  depending  upon  the  PCL  or  POP  jumper  connections  on  the 
digital  interrupt  module.  The  driver  will  assume  that  at  least  one  of 
these  signals  is  always  asserted. 

The  relative  module  number  indicates  the  module  oi'.  which  the  change  of 
state  was  recognized. 

The  module  data  word  records  data  received  at  the  time  the  interrupt 
was  serviced. 

The  generic  code  identifies  the  type  of  module  that  caused  the 
interrupt.  A  digital  Interrupting  module  may  have  the  value  1,  2,  or 
3  as  selected  by  user-installed  jumpers  on  the  module. 


18. 3.^^.2   Disconnect  from  Digital  Interrupts  -  This  function  allows   a 
task  to  terminate  the  processing  of  digital  interrupt  data. 

QIO  DPB  format; 

QIOSC  lO.DCI,... 


O 
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Return  Status; 


IS. sue  -  Function  successfully  completed.   Second  t/0  status  word 

is  n. 

IE. CON  -  Task  was  not  connected.   Second  I/O  status  word  is  0. 


18.3.^.1  Connect  to  Counter  Nodule  Interrupts  -  This  function  allows 
a  single  task  to  receive  counter  interrupt  data. 

QIO  DPS  format: 

QIOSC  lO.CTI , . . . ,<stadd,sizb,tevf ,arv> 

•tadd 

The  smarting  address  of  circular  buffer  (must  be  word  aligned). 

•  iib 

The  length  of  buffer  in  bytes  (must   be   even)  .    Minimum   buffer 
length  is  12  bytes. 

tevf 

The    trigger   event    flag   number. 

arv 

The  starting  address  of  table  of  initial  counter  values  (must   be 
word  al igned)  . 

Word  03  defines  an  array  of  initial  counter  values.  One  entry  is 
required  for  each  counter  installed  in  a  physical  unit.  Entries  are 
paired  with  modules  in  logically  ascending  sequence.  The  counter  is 
set  to  the  initial  value  upon  receipt  of  the  connect  function  and 
whenever  an  overflow  interrupt  occurs  (that  is,  when  the  count  reaches 
0). 

Return  Status: 

IS. sue  -  Function  successfully  completed.  The  second  I/O  status 
word  contains  the  number  of  words  passed  per  interrupt 
in  the  low  byte,  and  the  initial  FORTRAN  index  in  the 
high  byte. 

IE. BYT  -  Buffer  address  is  byte  aligned  or  length  in  an  odd 
number  of  bytes. 

IE. CON  -  Interrupt  already  connected  to  another  task. 
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IE. IBP  -  Invalid  avant  flaq  nunbar. 

IB.PRI  -  Task  chackpointabla  and  not  flxad  in  nanory. 

IB.8PC  -  Intarrupt  circular  buffar  or  table  of  initial  valuas  was 

not   wholly  within   tha  addrass  spaca  of  tha   task. 

Altarnativaly,  tha  buffar  was  too  snail   for  a   singla 
data  antry  (six  words  minimua) . 

Bntry  Format: 

WD  00  -  Existanca  indicator 

MD  01  -  Modula  data 

WD  02  -  Relative  nodule  nunbar 

WD  03  -  Generic  coda  (4,  5,  or  6) 


18.3.6.4  Sat  Counter  Initial  Value  -  This  function  allows  a  counter 
initial  value  to  be  established.  A  task  need  not  be  connected  to 
counter  interrupts  to  perform  this  function. 

010  DPB  fornat: 

OIOSC  IO.ITI,...,<nn,lc> 


■n 


ic 


The  relative  module  number. 


Tha  new  initial  count. 


Return  Statust 

IS. sue  -  New  value  submitted  for  output  to  the  controller.   The 
second  word  of  I/O  status  is  sat  to  0. 

IE. MOD  -  Nonexistent  module  number  specified. 

Upon  receipt  of  the  request,  the  new  initial  value  is  inmediately 
queued  for  output  to  the  controller.  The  counter  is  reinit < alixed 
with  this  value  on  overflow  if  a  task  is  connected  to  <.ountar 
interrupts. 


18.3.6.5  Disconnact  from  Counter  Interrupts  -  This  function  allows  a 
task  to  terninate  counter  interrupt  processing 

QIO  DPB  format: 

OIOSC  10. DTI,... 
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Return  Status: 


IS. sue  -  Function  successfully  completed.   The  second  word  of  I/O 
status  is  set  to  0. 

IE. CON  -  Task  was  not  connected  to  timer  interrupts. 

After  disconnect  is  complete,  counters  are  not  reset   to   the   initial 
value  at  the  time  of  the  interrupt. 


18.3.6.6  Connect  to  Terminal  Interrupts  -  This  function  allows  a  task 
to  receive  terminal  inputs  from  the  selected  ICRll  controller. 

QIO  DPB  format: 

OIOSC  lO.CTY, . . . ,<stadd,sizb,tevf> 

stadd 

The  address  of  the  circular  buffer  (must  be  word  aligned). 

sixb 

The  length  of  buffer  (must  be  even) .   The  minimum  buffer   length 
is  12  bytes. 

tevf 

The  trigger  event  flag  number. 

Return  Status: 

IS. sue  -  Function  successfully  completed.  The  second  I/O  status 
word  contains  the  number  of  words  passed  per  interrupt 
in  the  low  byte,  and  the  initial  FORTRAN  index  in  the 
high  byte. 

IE. BYT  -  Buffer  is  byte  aligned  or  length  is  an  odd  number  of 
bytes 

IE. CON  -  Interrupt  already  connected  to  another  task. 

lE.IEF  -  Invalid  event  flag  number. 

IE. MOD  -  Nonexistent  device.   Controller  is  ICSll. 

lE.SPC  -  Interrupt  circular  buffer  was  not  wholly  within  the 
address  space  of  the  task.  Alternatively,  the  buffer 
was  too  small  for  a  single  entry  (six  words  minimum) . 

Entry  Format; 

WD  00  -  Existence  indicator 

WD  01  -  High  byte  ■  0,  low  byte  ■  terminal  input  character 

WD  02  -  Relative  module  number  (normally  0) 

WD  03  -  Generic  code  indicator  (normally  0) 
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Not*  that  words  2  and  3  arc  nonzero  only  when  the  entry  was  made  as 
the  result  of  a  nonrecoverable  controller  error. 

All  remote  terminal  data  is  conveyed  to  the  requesting  task  as   input, 
but  with  the  parity  bit  removed. 

NOTF 

Remote  terminal  input  is  not   echoed   by 
the  driver. 


18.3.f).7   Disconnect  from  Terminal  Input  -  This  function  allows  a  task 
to  discontinue  the  processing  of  terminal  input. 

010  DPB  format: 

QIOSC  lO.DTY,... 

Return  Status: 

IS. sue  -  Function  successfully  completed.   The  second  word  of  I/O 
status  is  set  to  0. 

IE. CON  -  Task  was  not  connected  to  remote  terminal  interrupts. 


18.3.7  Activating  a  Task  by  Unsolicited  Interrupts 

The  functions  described  in  the  following  paragraphs  provide  the 
capability  of: 

1.  Activating  a  task  in  response  to  unsolicited  interrupts 

2.  Interrogating   the  driver   to  determine   the   reason   for 
activation 

3.  Removing  a  task  from  the  activation  list 

The  QIO  DPB  parameters  specify  the  task  name,  an  optional  trigger 
event  flag  to  be  set  if  the  task  is  active,  and  device-dependent 
parameters  that  identify  the  interrupt  sourc^,  A  task  is  linked  to 
interrupts  (that  is,  made  eligible  for  activation)  provided  that: 

1.  The  resource  exists. 

2.  The  task  is  installed. 

3.  No  other  task  is  linked  to  the  resource. 

If  another  task  is  linked  to  the  resource,  the  driver  will  reject  the 
request  with  a  status  of  resource-in-use  (lE.RSU).  A  resource  is 
defined  as  a  single  interrupt  point,  remote  terminal  (Control-C  input 
only) ,  or  counter  module. 
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On  the  occurrence  of  the  appropriate  interrupt,  the  task  is  made 
active  if  dormant;  otherwise,  a  trigger  event  flag,  if  specified,  *3 
set.  The  task  may  interrogate  the  driver  to  determine  the  conditions 
that  caused  activation,  and  to  signify  interrupt  recognition.  The 
function  of  the  event  flag  is  to  allow  such  a  task  to  recognize  an 
event  that  has  occurred  while  the  task  was  active.  Recognition  is 
ensured  prior  to  he  completion  of  task  execution  ny  issuing  the  Exit 
If  system  directive  followed  by  the  Clear  Event  Flag  directive. 

The  linkage  betwefan  a  task  and  a  specific  interrupt  is  removed  by 
issuing  the  appropriate  unlink  request  with  thn  QIC  directive. 

Only  one  task  may  be  associated  with  ijach  interrupt  source  (that  is, 
one  task  per  digital  interrupt  point,  terminal  input,  or  counter 
module. 


NOTE 

The   MCR   command   REMOVE   automatically 
unlinks  a  task  from  all  interrupts. 


18.3.7.1   Link  a  Task  to  Digital  Interrupts  -  This  function   allows   a 
task  to  be  activated  on  the  occurrence  of  digital  interrupts. 

QIO  DPB  format! 

OIOSC  10. LDI , . . . ,<tname, f ,tevf 1 ,pn,csm> 

tname 

A  1-  to  6-character  alphanumeric  task  name   in   2-word,   r.adlx-50 
format. 


tevf 


Pn 


csm 


The  trigger  event  flag  (0  =  none). 


The  point  number  (must  be  aligned  on  a  module  boundary). 


The  chance-of-state  mask. 

The  change-of-state  mask  indicates  those  bits  for  which  a  chanye  of 
state  in  the  direction  specified  by  the  PCL  and  POP  jumpers  causes  the 
task  to  be  activated.  Only  one  task  may  be  linked  to  a  given 
interrupt  point.   A  0  change-of-state  mask  Is  not  permitted. 
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Return  Status: 


IS. sue  -  function  succassfully  coaplctcd.   The  sacond  word  of  I/O 
•tatus  Is  sat  to  0. 

IB. BAD  -  Chanqa-of-stata  ut.uk   sat  to  0. 

II. IBP  -  Invalid  avant  fla-j  nuabar. 

IB. NOD  -  Nonaxistant  nodula  or  point   not   alignad  on  a  nodula 
boundary. 

IB. NOD  -  Insufficiant  dynaaic  aaaiory  to   allocata   sacondary 
control  block. 

lE.NST  -  Task  "tnaaa"  is  not  installad. 

lE.RSU  -  Ona  or  aora  of  tha  specified  points  is  in  use  by  ether 
tasks. 


18.3.7.2  Link  a  Task  to  Counter  Interrupts  -  This  function  allows  a 
task  to  be  activated  by  neans  of  an  interrupt  from  a  single  counter 
■odule. 

QIO  DPB  foraat: 

OIOSC  lO.LTI,...  ,<tnaine,  [,tevf]  ,cn(,icl  > 

tnaaie 

A  1-  to  A-character  alphanuaeric  task  nana   in   2-word   Radix-SO 
foraat. 

tavf 

The  trigger  event  flag  (0  ■  none). 

en 

The   relative  aodule  ituaber. 

ic 

The  counter  value  (optional). 

The  counter  value  if  nonzero,  is  used  to  reinitialize  the  module  in  a 
manner  siailar  to  that  described  for  the  Set  Counter  function  in 
Section  18.3.'>.4.  Initialization  may  be  bypassed  by  setting  this 
parameter  to  0. 

Return  Status: 

IS. sue  -  Function  successfully  completed.   The  second  word  of  I/O 
status  is  set  to  0. 

IE. IBP  -  Invalid  event  flag  number. 
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IE. MOO  -  Non«xiat«nt  modul*  specified. 

IB. NOD  -  Insufficient  dynamic  memory  to   allocate  a   secondary 
control  block. 

lE.RSU  -  Counter  is  linked  to  another  task. 


18.3.7.3  Link  a  Task  to  Terminal  Intewrupts  -  This  function  allows  a 
task  to  be  activated  by  means  of  an  interrupt  from  a  remote  terminal. 
The  task  will  be  activated  only  in  response  to  the  Control-C  character 
(octal  003) . 

010  DPB  format! 

OIOSC  lO.LTY,... ,<tname, t,tevf)> 

tname 

A  1-  to   fi-character  alphanumeric   task   name      in     2-word,      Radlx-50 
format. 

tevf 

The  trigger  event  flag  (0  ■  none) . 

Return  Status: 

IS. sue  -  Function  successfully  completed.   The  second  word  of  I/O 
status  is  0. 

IB.ICP  -  Invalid  event  flag  number. 

IE. MOD  -  Nonexistent  module  (unit  is  ICSll  controller). 

IE. NOD  -  insufficient  dynamic   storage   to   allocate    secondary 
control  block. 

lE.NST  -  Task  "tname"  is  not  installed. 

lE.RSU  -  Remote  terminal  is  linked  to  another  task. 


18.3.7.4  Link  a  Task  to  Error  Interrupts  -  This  function  allows  a 
single  task  to  be  activated  whenever  a  remote  unit  power-fail  or 
nonrecoverable  serial  line  error  is  detected  on  any  or  all  remote 
units  in  a  system.  Only  one  task  within  a  system  may  be  linked  to 
error  interrupts.  Once  linked,  the  selected  task  may  receive  error 
reports  from  any  ICR  controller. 

QIO  DPB  format: 

QIO$C  IO.LKE,...,<tname,[,tevf]> 


tnaae 


A  1-  to  ^-character  alphanumeric  task   name   in   2-word   Radix-50 
format. 


18-27 


INDUSTRIAL  CONTROL  SUBSYSTEMS 

t«vf 

Th«  trigger  event  flag  (0  ■  none)  . 

Return  Status: 

IS. sue  -  Function  successfully  completed.   The  second  word  of  I/O 
status  is  0. 

lE.IEF  -  Invalid  event  flag  number. 

IE. IPC  -  No  ICRll  subsystems  are  installed. 

IE. NOD  -  Insufficient  dynamic   storage   to  allocat«   secondary 
control  block. 

lE.NST  -  Task  "tname"  is  not  installed. 

lE.RSU  -  Another  task  is  linked  to  error  interrupts. 


18.:). 7. 5  Read  Activating  Data  -  This  function  allows  a  task  to 
determine  the  conditions  that  caused  it  to  be  activated. 

QIO  DPS  format: 

QIO$C  lO.RAD, . .. ,<stadd> 

stadd 

The  address  of  6-word  buffer  to  receive  activation  data  (must   be 
word  aligned)  . 

The  buffer  receives  data  in  the  following  format: 

WD  00  -  Activation  indicator 

WD  01  -  Physical  unit  number 

WD  02  -  Generic  code 

WD  03  -  Relative  module  number 

WD  04  -  Hardware  dependent  data 

WD  05  -  Hardware  dependent  data 

The  activation  indicator  is  similar  in  function  to  the  existence 
indicator  used  when  reading  circular  buffer  entries.  The  Indicator  is 
set  to  +1  on  the  occurrence  of  an  interrupt  to  t^hlch  the  requesting 
task  is  linked,  and  the  appropriate  data  Is  stored.  The  indicator  Is 
cleared  when  the  data  is  solicited  by  the  task.  If  an  interrupt 
linked  to  the  task  occurs  and  the  parameter  is  nonzero  then  the 
previously  stored  data  is  not  modified  and  the  driver  sets  this 
element  with  the  two's  complement  of  the  number  of  linked  interrupts 
not  recorded. 

The  physical  unit  number  specifies  the  controller  that  received  the 
interrupt. 
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The  generic  code  is  Identical  to  that  specified   for  circular   buffer 
entries,  namely: 

0      -  Terminal  (Control-C) 

1,2,3   -  Digital  interrupt 

4,5,fi   -  Counter  interrupt 

177770  -  Fatal  controller  error 

Hardware-dependent  data  is   associated   with  generic  code   and   will 
consist  of  the  following: 

Terminal : 

WD  04  -  Terminal  buffer  contents  (low  byte) 

WD  05  -   Undefined 
Digital  Interrupts: 

WD  04  -   Module  data 

WD  05  -  Change-of-state  indicator 
Counter : 

WD  04  -   Module  data 

WD  05  -   Undefined 
Fatal  Controller  Error; 

WD04   -  Contents  of  ICSR  register  (see  Table  18-7) 

WD05   -   Contents  of  ICAR  register  (see  Table  18-8) 

Return  Status: 

IS. sue  -  Function  successfully  completed.   The  second  word  of  I/O 
status  is  0. 

IE. BYT  -  Buffer  address  is  aligned  on  an  odd  byte  boundary. 

lE.NLK  -  Task  "tname"  was  not  linked  to  interrupts. 

lE.SPC  -  Buffer  not  totally  within  the  task's  address  space. 

18.3.8  Unlink  a  Task  from  Interrupts 

The  functions  described   in   the   following   paragraphs   provide   the 
capability  of: 

1.  Unlinking  a  task  from  all  interrupts  on  a  controller 

2.  Selectively  unlinking  a  task  from  interrupts  by  module  type 
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18.3.8.1  Unlink  a  Task  froa  All  Intarrupta  -  This  function  unlinks  a 
taak  from  all  intarrupts  on  a  givan  controllar  and  from  arror 
intarrupts. 

QIC  DPS  format t 

0IO$C  IO.NLK,...,<tnama> 

tnama 

A  1-  to  6-charactar  alphanumaric  task   nama   in  2-word  Radix-50 
format. 

Raturn  Status i 

IS. sue  -  Function  succassfully  complatad.   The  second  word  of  I/O 
status  is  0. 

lE.NLK  -  Task  "tnama"  was  not  linked  to  interrupts. 


18.3.8.2  Unlink  a  Task  from  all  Digital  Intarrupts  -  This  function 
provides  the  capability  of  unlinking  a  task  from  all  digital  interrupt 
points  on  a  controller. 

QIO  OPS  format: 

QIO$C  IO.UDI,...,<tname> 

tnama 

a  1-  to  6-character  alphanumeric  task   name   in  2-word   Radix-50 
format. 

Return  Statusi 

IS. sue  -  Function  successfully  completed.   The  second  word  of  I/O 
status  is  0. 

lE.NLK  -  Task  "tname"  was  not  linked  to  the   specified  class  of 
interrupt. 

lE.NST  -  Task  not  installed. 

IE. MOD  -  Nonexistent  module  type  specified. 


18.3.8.3  Unlink  a  Task  from  Counter  Interrupts  -  This  function 
provides  the  capability  of  unlinking  a  task  from  all  counter  module 
interrupts. 

QIO  DPS  format: 

OlOSe  IO.UTI,...,<tname> 


tnaatt 


A  1-  to  6-character  alphanumeric  task   name   in   2-word   Radix-50 
format. 
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Return  Status: 


IS. sue  -  Function  successfully  complstsd.   Ths  second  word  of  I/O 
status  Is  0. 

IB.NLK  -  Task  "tnama"  was  not  llnkad  to  ths  spscifisd  interrupts. 

IB.NST  -  Task  not  installed. 

IE. MOD  -  Nonexistent  module  type  specified. 


18.3.8.4   Unlink  a  Task  fron  Terninal  Interrupts  -  This       function 
provides  the  capability  of  unlinking  a  task  from  terminal  interrupts. 

010  OPB  format! 

QIOSC  IO.UTY,...,<tname> 


tname 


A  1-  to  6-character  alphanumeric  task   name   in   2-word   Radix-50 
format. 


Return  Sta*-us: 

IS.'JC  -  Function  successfully  completed.   The  second  word  of  I/O 
status  is  0. 

lE.NLK  -  Task  "tname"  was  not  linked  to  the  specified  interrupts. 

lE.NST  -  Task  not  installed. 

IE. MOD  -  Nonexistent  module  specified   (that   is,   device   is  an 
ICSll  controller) . 


18.3.8.5  Unlink  a  Task  from  Error  Interrupts  -  This  function  provides 
the  capability  of  unlinking  a  task  from  all  error  interrupts. 

QIO  DPB  format: 

QIOSC  lO.UER, . . . ,<tname> 


tname 


A  1-  to  <)-character  alphanumeric  task  name   in   2-word   Radix-50 
format. 


Return  Status: 


IS. sue  -  Function  successfully  completed.   The  second  word  of  I/O 
status  is  0. 

lE.IFC  -  No  ICRll  controllers  exist  in  the  system. 

lE.NLK  -  Task  "tname"  was  not  linked  to  error  interrupts. 

lE.NST  -  Task  not  installed. 
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18.3.9  Terminal  Output 

This  function  allows  a  task  to  perform  output  to  the  terminal  device. 
Characters  are  output  exactly  as  they  appear  in  the  buffer.  The 
carriage  control  parameter  is  not  recognized.  It  should  be  noted  that 
only  one  interrupt  module  request  per  controller  (terminal  or  A/D)  may 
be  in  progress  at  a  given  time.  Ihus,  the  driver  will  not  initiate  an 
A/D  operation  on  a  given  controller,  until  any  terminal  output  in 
progress  for  that  controller  has  been  completed. 

QIC  DPB  format! 

0IO$C  lO.WLB, . . . ,<staddb,sizb> 

■taddb 

The  buffer  address  (may  be  odd) . 

sizb 

The  byte  count  (may  be  odd) . 

Return  Status: 

IS. sue  -  Function  successfully  completed.    Second   word   of   I/O 
status  contains  the  number  of  bytes  output. 

IE. MOD  -  Nonexistent  hardware  function.   Request  was   issued   for 
an  ICSll  controller. 


18.3.10  Maintenance  Functions 

The  functions  described  below  allow  a  privileged  task  to  enable  and 
disable  error  reporting  while  troubleshooting  or  maintenance  on  a 
remote  unit  is  in  progress. 


18.3.10.1  Disable  Hardware  Error  Reporting  -  This  function  allows  a 
privileged  task  to  disable  error  reporting  and  error  interrupts,  and 
restrict  access  to  the  controller  while  remote  unit  troubleshooting  or 
module  calibration  is  In  progress  (see  Section  18.5.1).  Upon  receipt 
and  validation  of  the  request,  error  interrupts  are  disabled  and 
subsequent  controller  time-outs  are  Ignored.  The  occurrence  of  device 
time-out  while  A/D  conversion  or  remote  terminal  input  Is  in  progress 
results  in  termination  of  the  request  with  the  error  code  IE. ABO. 
When  error  reporting  is  disabled  in  this  manner,  access  to  the 
controller  for  input  or  output  to  I/O  modules  is  restricted  to 
privileged  tasks.  All  other  requests  not  requiring  the  transmission 
of  data  to  or  from  the  device  are  permitted  for  all  tasks.  Such 
requests  are  as  follows: 

1.  Disconnect   from   digital,   counter,    or    remote    terminal 
interrupts 

2.  Unlink  from  interrupts 

3.  Read  activating  data 
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4.  Link  to  digital,  remote  termlial,  or  error  interrupt* 

5.  Connect  a  buffer  to  digital  or  remote  terminal  Interrupts 

All  other  requests  not  issued  by  a  privileged  task  are   rejected   with 
th«  error  code  lE.DNR. 

010  DPB  format: 

0IO$C  lO.FLN,... 

Return  Status: 

IS. sue  -  Function  successfully  completed 
lE.PLN  -  Unit  already  off  line 
lE.PRI  -  Task  not  privileged 


18.3.10.2  Enable  Hardware  Error  Reporting  -  This  function  allows  a 
privileged  task  to  enable  error  reporting  and  device  error  interrupts. 
Upon  receipt  and  validation  of  the  function,  all  device  error 
interrupts  are  enabled  and  the  unit  is  marked  on  line.  These  actions 
are  performed  regardless  of  the  current  state  of  the  unit.  010  DPB 
format : 

OIOSC  lO.ONL,... 

Return  Status: 

IS. sue  -  Function  successfully  completed 
lE.PRI  -  Task  not  privileged 


18.3.11   Special  functiions 


18.3.11.1   I/O  Rundowr  -  An  I/O  rundown   request   from   the  Executive 

will   automatically   cause   the   task   to   be   disconnected  from   all 

interrupts.   The  rundown  operation  is  not  finished  until  any  A/D  input 
it   progress  for  the  task  has  been  completed. 


18.3.11.2  Kill  I/O  -  The  kill  I/O  function  allows  a  task  to  initiate 
I/O  rundown  processing  for  itself  on  any  device.  Request  processing 
is  identical  to  that  described  for  I/O  rundown. 

QIO  DPB  format: 

OIOSC  lO.KIL,... 

Return  Status: 

IS. sue  -  Function  successfully  completed 
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18.4   FORTRAN  INTBRPACB 


Tabic  18-ft  lists  th«  FORTRAN  interface  subroutines  supported  for  the 
ICS/ICR  subsysten.  (D)  Indicates  a  direct  access  call.  The  six 
subroutines  supported  by  the  DSS/DRS  driver  are  indicated  by  a 
footnote. 


Unless  specifically  noted,  all  subroutines  are  reentrant  (but  not 
necessarily  position-independent)  and  may  be  placed  in  an  absolute 
resident  library. 


Table  18-f> 
FORTRAN  Interface 


Subroutine 

Function 

AIRD/AIRDW 

Input  analo9  data  from  multiple  channels  in   random 
sequence 

AISO/AISOW 

Read  a  series  of  sequential  analog   input   channels 
at  random  gain 

AO/AOW 

Perform  analog  output  on  several  channels 

ASICLN/ 
ASUDLN 

Assign  a  LUN  to  an  ICS/ICR  controller 

asislnI 

Assign  a  LUN  to  a  DSS/DRS  contioller 

CTDI 

Connect   a   circular   buffer   to   receive   digital 
interrupt  data 

CTTI 

Connect  a   circular   buffer   to   receive   counter 
interrupt  data 

CTTY 

Connect  a  circular  buffer  to  receive   ICRll   remote 
termin-jl  data 

DFDI 

Discv'jnnect  a  buffer  from  digital  interrupts 

DFTI 

Disconnect  a  buffer  from  counter  interrupts 

DFTY 

Disconnect  a  buffer  from  remote  terminal  interrupts 

Dl/Diwl 

Read  several  16-point  digital  sense  fields  (D) 

DCL/DOLWl 

Latch  or  unlatch  several  16-point  bistable  output 
fields 

DOM/DOMW 

Pulse  multiple  16-point  momentary  digital   output 
fields 

lnkI 

Link  a  task  to  unsolicited  interrupts 

OFLIN 

Suppress  error  reporting.   Place  unit  in  not   ready 
status 

ONLIN 

Enable  error   reporting.    Return   unit   to   ready 
status 

RCIPT 

Read  a  single  digital  interrupt  point  (D) 

(continued  on  next  page) 
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Tabl*  18-«   (Cont.) 
FORTRAN  Intarfac* 


Subroutine 

Function 

RDACT^ 

Road  interrupt  activation  data 

RDDI 

Road  tho  digital  interrupt  circular  buffer 

RDTI 

Read  the  counter  interrupt  circular  buffer 

RDCS 

Read  digital   interrupt  circular  buffer;    return 
data   on  only  those   points  for  which  a  change  of 
state  has  been  recognized 

RDWD 

Read  digital  interrupt  circular  buffer;   return  a 
full  data  word 

R8TI 

Read  a  single  counter  module  (D) 

RTO/RTOW 

Perform  output  to  a  remote  ICRll  terminal 

unlnrI 

Unlink  a  task  from  unsolicited  interrupts 

1.  These  subroutines  are  supported  by  the  DSS/DRS  driver. 


18.4.1  Synchronous  and  Asynchronous  Process  Control  I/O 


The  Instrument  Society  of  America  (ISA)  stand 
synchronous  and  asynchronous  I/O.  Synchronous 
appending  a  W  to  the  name  of  the  subroutine  (for 
Except  for  analog  input  and  terminal  output,  all 
process  control  subroutines  are  serviced  immediatel 
are  complete  upon  return  to  the  issuing  ta'^  In  s 
no  functional  difference  between  the  synchronou;: 
forms;  however,  both  forms  of  the  name  are  recog 
of  A/D  input  and  terminal  output,  the  subroutines 
distinct.  If  the  asynchronous  form  is  used,  exec 
the  calling  program  must  periodically  test  the 
completion. 


ard  provides  for 
I/O  is  indicated  by 
example,  AO/AOW) . 
QIOs  issued  by  the 
y  by  the  driver  and 
uch  cases,  there  is 

and  asynchronous 
nized.   In  the  case 

are  functionally 
ution  continues  and 

status  word  for 


18.4.2  Return  Status  Reporting 

The  I/O  status  parameter  is  a  2-word  integer  array.  The  first  element 
of  the  array  receives  the  status  of  the  FORTRAN  call  in  accordance 
with  ISA  convention. 

This  array  serves  two  purposes: 

1.  It  is  the  2-word  I/O  status  block  to  which  the  driver  returns 
an  I/O  status  code  on  completion  of  an  I/O  request. 

2.  The  first  word  of  the  status  block  receives  a  status  code 
from  the  FORTRAN  interface  subroutine  in  ISA-compatible 
format,  with  the  exception  of  the  I/O  pending  condition, 
which  is  indicated  by  a  status  of  0.  The  ISA  standard  code 
for  this  condition  is  +2. 


18-35 


INDUSTRIAL  CONTROL  SUBSYSTBMS 


For  asynchronoua  analog  input  and  terminal  output,  status  is  set  by 
means  of  an  asynchronous  trap;  therefore,  the  trap  mechanism  must  be 
enabled  while  these  functions  are  in  progress. 

For  compatibility,  the  2-trard  status  block  is  also  required  for  status 
returned  by  the  direct  access  calls.  Errors  of  this  type  that  may  be 
returned  arts 


Word  1  -  3 
Word  1  -  4-321 


Number  jf  points  requested  is  0, 
Invalid  ICS/ICR  module. 


The  status  code  must  be  interpreted  in  the  context   of   the   function 
requested;   however,  the  following  general  conditions  will  apply: 


Contents  of  Status  Word  1 
0 

♦I 

+  3 

3<Word  K300. 
Word  1  >  300 


Meaninti 

Operation  pending,  I/O  in  progress 

Successful  completion 

Error  in  a  calling  argument  has  been 
f^eterted  by  the  interface  subroutine 

010  directive  rejected.   Actual  error 
code  -  -(WORD  1-3) 

Request  rejected  by  driver.    Actual 
error  code  ■  -{WORD  1  -  300) 


Table  18-7  lists  all   possible   status  values:    the   FORTRAN  value, 
assembly  language  mnemonic,  actual  value,  and  related  definition. 


Table  18-7 
Return  Status  Summary 


FORTRAN 
Interface 
Value 

Assembly 
Language 
Value 

Assembly 
Language 
Mnemonic 

Definition 

+0 

4-0 

IS.PND 

Operation  pending 

+1 

4-1 

IS. sue 

Successful  completion 

+  3 

none 

none 

Error   detected   In    FORTRAN 
calling  sequence 

4-4 

-1 

lE.UPN 

Insufficient  dynamic   storage 
to  allocate  I/O  packet 

4-8 

-5 

lE.ULN 

Unasslgned  LUN 

-6 

-fi 

lE.LNL 

LUN  usage  interlocked 

+99 

-9fi 

lE.ILU 

Invalid  LUN 

4-100 

-97 

lE.IEF 

Invalid  event  flag  number 

(continued  on  next  page) 
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Table  18-7   (Cont.) 
Return  Status  Summary 


FORTRAN 
Interface 
Value 

Assembly 
Language 
Value 

Assembly 
Language 
Mnemonic 

Definition 

+  101 

-98 

lE.ADP 

Part  of   DPB   out   of   user's 
addressing  space 

+  102 

-99 

lE.SDP 

Invalid  DIG  or  DPB  size 

+  301 

-1 

IE. BAD 

Bad  parameters 

+  302 

-2 

lE.IFC 

Invalid  I/O  funrtio   code 

+  303 

-3 

lE.DNR 

Device  not  ready 

+  306 

-6 

lE.SPC 

Illegal  buffer 

+  315 

-15 

IE. ABO 

Request  aborted 

+  316 

-16 

lE.PRI 

Privilege  violation 

+  317 

-17 

lE.RSU 

Resource  in  use 

+  319 

-19 

IE. BYT 

Buffer  address  or   length   is 
odd 

+  321 

-21 

IE. MOD 

Illegal  module  number 

+  322 

-22 

IE. CON 

Another     task      already 
connected  to  interrupts 

+  323 

-23 

IE. NOD 

Insufficient   dynamic   memory 
to  allocate  secondary  control 
block 

+  379 

-79 

lE.NLK 

Task  not  linked  to  interrupts 

+  380 

-80 

lE.FLN 

ICRll  already  off  line 

+  381 

-81 

lE.NST 

Task  is  not  installed 

+  397 

-57 

lE.IEF 

Invalid  event  flag  number 

18.4.3  Optional  Arguments 

The  calling  sequences  discussed  in  subsequent  sections  frequently 
contain  optional  arguments.  These  arguments  are  enclosed  in  square 
brackets  within  the  calling  sequence  description.  A  statement 
containing  such  arguments  may  be  written  with  these  parameters  deleted 
by  truncating  the  argument  list  if  the  optional  parameters  are  at  the 
end  of  the  calling  sequence,  or  by  replacing  them  with  commas  if  they 
are  embedded  elsewhere  in  the  list.  Consider  the  routine  XYZ  below 
having  two  optional  arguments: 

CALL  XYZ (ibuf  [,ilen1  f,ivall) 

If  the  argument  ival  is  to  be  omitted,  the  calling  sequence  would  be: 

CALL  XYZ ( IBUF, ILEN) 
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When  an  optional  arqumcnt  in  the  middle  of  the  list  is  to  b«  omitted, 
it  is  replaced  with  a  comma.  Consider  the  routine  XY2 ,  above.  The 
following  statement  is  used  to  omit  the  parameter  ilent 

CALL  XYZ(IBUF,,IVAL) 

NOTE 

In  some  subroutines,  lun  --  the  logical 
unit  number  --  is  indicated  to  be  an 
optional  argument.  It  is  optional  only 
if  one  of  the  Assign  LUN  subroutines  has 
been  called  (ASICLN,  ASUDLN,  ASISLN)  . 
Otherwise,  the  lun  argument  is 
mandatory. 


18.4.4  Assigning  Default  Logical  and  Physical  Units  for  Input  and 
Output  -  ASICLN/ASUDLN  (ICS/ICR)  and  ASISLN  (DSS/DRS) 

The  following  subroutines  must  be  called  to  assign  and  record  a 
default  LUN  and  physical  unit  if  either  parameter  is  to  be  unspecified 
in  subsequent  FORTRAN  calls  for  which  these  parameters  are  optional. 

Calling  Sequence: 

CALL  ASICLN([lun1  [fidsw]  [,iunt1) 
CALL  ASUDLN (r lun]  [,idswl  [,iunt]) 
CALL  ASISLN(lun[,idsw] [,iant] ) 

Before  a  task  can  issue  the  call  to  ASUDLN,  the  ASN  command  must  be 
issued  through  NCR  to  assign  logical  device  UDnn  to  the  appropriate 
physical  ICS/ICR  unit. 

Argument  Description: 

lun  -  An  integer  variable  whose  value  is  the  number  of  the  LUN 
to  be  assigned  to  the  physical  >jnit  specified  by  iunt  or 
unit  0.  If  unspecified,  no  LUN  is  assigned.  The  lun 
argument  is  mandatory  for  ASISLN  (used  for  DRSll  only). 

idsw  -  An  optional  integer  variable  to  receive  the  result  of 
the  assign  lun  directive. 

iunt  -  An  optional  integer  variable  that  specifies  the  unit 
number  to  be  assigned.   Assumed  to  be  0  if  omitted. 

Return  Status: 

The  following  values  are  returned  to  idsw: 

♦1     -  Assignment  or  function  successfully  completed. 

•i  -  LUN  usage  is  interlocked  because  LUN  is  assigned  to  a 
device  that  is  attached  to  another  device,  or  a  file  is 
currently  open  on  the  LUN. 

-96    -  Invalid  LUN. 

The  call  to  ASUDLN  assigns  a  LUN  to  logical  device  UD:  and  is 
provided  for  compatibility  with  existing  UDCll  software.  The  call  to 
ASICIN  assigns  a  LUN  to  device  IC:.  The  call  to  ASISLN  assigns  a  LUN 
to  device  IS: . 
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Upon  successful  issuanc*  of  ths  Assign  LUN  directive,  the  subroutine 
executes  a  Get  LUN  Infornatlon  directive  to  obtain  the  actual  unit 
numbers  to  be  saved.  It  Is  therefore  possible  to  alter  the  default 
physical  unit  referenced  In  a  direct  access  call,  by  means  of  the  ASN 
MCR  function,  provided  that  such  logical  assignments  are  done  before 
the  task  is  made  active. 

Examples t 

1.  Assign  LUN  5  to  TCR  unit  3. 

CALL  ASICLN  (5,IERR,3) 
IP(IERR)  20,10,10 
10   

2.  Assign  LUN  1  to  logical  device  UD:,  unit  0 

a.  The  followinq  MCR  command  is  Issued  to  create  logical 
device  UDO:,  and  assign  all  references  to  physical  device 
IClt. 

>ASN  ICl:   -  UD: 

b.  The  FORTRAN  call 

CALL  ASUDLN  (1) 

assigns  logical  device  UDO:  to  LUN  1.  Because  of  the 
previous  ASN  command,  the  Executive  will  assign  this  LUN 
to  physical  device  ICl:  and  return  a  value  of  1  for  the 
unit  number  in  response  to  the  GET  LUN  Information 
directive.  This  value  will  be  stored  and  later 
referenced  whenever  the  physical  unit  number  is 
unspecified  in  any  of  the  FORTRAN  calls  that  reference 
the  I/O  page  directly. 


Assign  LUN  6  to  logical  device  IS:,  unit  2. 


3. 

CALL  ASISLN(6,,2) 

18.4.5  Analog  Input 

The  following  routines  provide  the  capability  of  performing  A/D  input: 

AIRC/AIRDW  -  ISA  Standard  call  to  read  multiple  channels  in 
random  order.  This  call  requires  one  or  more 
control  variables  containing  A/.'  channel  and  gain 
in  the  format  shown  in  Table  18-5  (Section  18.3.2). 

AISQ/AISQW  -  ISA  Standard  call  to  read  multiple  channels  in 
sequential  order. 


18.4.5.1  AIRD/AIRDW:  Analog  Input  -  Specified  Channel  Sequence  -  The 
ISA  standard  call  provides  the  capability  of  reading  multiple  A/D 
channels  in  a  specified  sequence. 
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Calling  Sequence t 

CALL  AIRD(inm,icont,id«ta[,ieb1  ,lun) 
or 

CALL  AIRDW(lnin,Icont,. .  .etc.) 

Argument  Descriptionat 

Inm  -  Integer  variable  apecifying  the  number  of  channela  to 
be  read. 

icont  -  An  integer  array  of  size  inm  containing  control  data  in 
the  format  shown  in  Table  18-5  (Section  18.3.2). 

idat  -  An  integer  array  of  dimension  inm  to  receive  the 
converted  values.  Each  element  in  the  array  is  paired 
with  a  control  element  in  icont  that  defines  the 
channel  and  gain. 

isb  -  An  optional  2-word  integer  array  to  receive  the  results 
of  the  call  as  follows: 

♦1  -  Conversion  successfully  completed.  The 
second  word  contains  the  number  of  channels 
converted. 

♦3    -  Number  of  channels  requested  was  0. 

♦4  -  Insufficient  dynamic  storage  to  allocate 
I/O  packet. 

4't    -   LUN  was  not  assigned. 

+99    -   Invalid  LUN. 

+301  -  At  least  one  invalid  control  word  was 
specified.  The  second  I/O  status  word 
contains  the  number  of  channels 
successfully  converted. 

+303  -  Device  not  ready.  Interrupt  response  was 
not  received  from  an  A/D  channel  within  one 
second  after  initiation.  The  second  word 
of  I/O  status  contains  the  number  of 
channels  successfully  converted. 

+30fi  -  Control  or  data  buffer  not  wholly  within 
the  user's  addressing  space. 

+319  -  Control  or  data  buffer  is  byte  aligned. 

lun  -  An  integer  variable  specifying  the  ICS/ICR  logical  unit 
number.   This  parameter  is  required. 

Example: 

The  following  example  illustrates  how  A/D  throughput  can  be  increased 
when  several  lAD-IA  A/D  Converters  are  in  a  system.  This  is 
accomplished  by  means  of  interleaved  samples  that  initiate  parallel 
conversions  on  each  module.  Samples  are  to  be  obtained  from  12 
channels  on  3  lAD-IA  A/D  converter  modules  at  a  gain  of  1. 
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e 

C  PROGRAM  TO  SAMPLE  12  A/D  CHAMMELS 

C  IN  RANDOM  SEOUENCE  FOR  MAXIMUM 

C  THRUPUT. 

C 

C  CHANNELS  TO  BE  SAMPLED* 

C 

t         " 

#  1      -A/D  MODULE  0 

c 

9 


t 


120 

121      -A/D  MODULE  1 

122 

123 

240 

241      -A/D  MODULE  2 

242 
C  243 

C 

C  INTERLEAVED  SEQUENCE  FOR  MAXIMUM 
C  THRUPUT. 
C 

ff  0 

0        120 
e        240 

e  1 

e  121 

9        241 

e  2 

e  122 

e       242 

e  3 

C        123 

C        243 

C 

C  THE  FORTRAN  CONVENTION  FOR  ARRAY 

C  STORAGE  CAN  BE  USED  TO  REPRESENT 

C  THE  ABOVE  SEQUENCE  IN  AN  N  X  I  INTEGER 

C  CONTROL  ARRAY.   WHERE: 

C 

C        N  -  NUMBER  OF  MODULES  TO  BE  SAMPLED 

C        I  -  NUMBER  OF  SAMPLES  PER/MODUOE 

C 

C  ALLOCATE  STORAGE  FOR  CONTROL  ARRAY 

C 

DIMENSION  ICON!  (3,4) 
C 

C  INITIALIZE  CONTROL  ARRAY  FOR  lAD-IA  MODULE  0 
C 

DATA  ICONT(1,1),ICONT(1,2),ICONT{1,3),ICONT(1.4)/0,1,2,3/ 

C  INITIALIZE  CONTROL  ARRAY  FOR  lAD-IA  MODULE  1 
C 


DATA  IC0NT(2,1) ,ICONT(2,2) ,ICONT(2,3) ,ICONT(2,4)/120,121,122,123/ 

C  INITIALIZE  CONTROL  ARRAY  FOR  lAD-IA  MODULE  2 
C 

DATA  ICONT(3,l),ICONT{3,2),ICONT(3,3),ICONT(3,4)/240,24l,242,243/ 


C 

C  ALLOCATE  STORAGE  FOR  DATA  ARRAY 
C  IN  SIMILAR  FASHION  TO  FACILITATE 
C  CHANNEL  REFERENCES 
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DIMBN8I0N    IDATA    (3,4) 

e 

C        BEGIN  EXECUTABLE  STATEMENTS 

c 


c 

C  INITIATE  A/D  SYNCHRONOUS  CONVERSION  ON  LUN  3 
C 

CALL  AIRDM(12,ICONT,IDATA,,3) 


18.4.5.2  AISQ/AISOW:  Analog  Input  -  Sequential  Channel  Saquanc*  -  The 
ISA  standard  call  described  below  provides  the  capability  of  sampling 
multiple  A/D  channels  in  sequential  order.  Channels  are  sampled  in 
Increments  of  one,  beginning  with  the  channel  specified  in  icont(l). 

Calling  Sequence! 

CALL  AISO(inm,lcont,idata  f,l8b],lun) 
or 

CALL  AISQW( inm,icont. . .etc.) 

Argument  Descriptions: 

inm    -   Integer  variable  specifying  the  number  of  elements   to 
*  be  read. 

leont  -  An  integer  array  of  size  inm  containing  initial  channel 
in  the  first  element  only,  and  gain  in  the  format  shown 
in  Table  18-5  in  the  remaining  elements. 

idat  -  An  integer  array  of  size  inm  to  receive  the  converted 
values.  Bach  element  is  paired  with  the  corresponding 
control  element  in  icont  that  defines  the  gain 
parameter. 

Channels  are  sampled   sequentially  starting  with   the 
first  channel  specified  in  element  1  of  icont. 

isb  -  An  optional  2-word  integer  array  to  receive  the  results 
of  the  call  as  follows: 

4%  -  Conversion  successfully  completed.  The 
second  word  contains  the  number  of  channels 
converted. 

43    -  Number  of  channels  requested  was  0. 

■¥4  -  Insufficient  dynamic  storage  to  allocate 
I/O  packet. 

■  T~"        ■♦■8    -   LUN  was  not  assigned. 

.  _    -  +99   -   Invalid  LUN. 
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♦301  -  At  least  on*  Invalid  control  word  was 
specif  lad.  Tha  sacond  I/O  status  word 
contains  th*  number  of  channels 
successfully  converted. 

•f303  -  Device  not  ready.  Interrupt  response  was 
not  received  from  an  A/D  channel  within  one 
second  after  Initiation.  The  second  word 
of  I/O  status  contains  the  number  of 
channels  successfully  converted. 

+306  -  Control  or  data  buffer  Is  not  wholly  within 
the  user's  addressing  space. 

+319  -  Control  or  data  buffer  is  byte  aligned. 

Ian    -  An  Integer  variable  containing  the  logical  unit  number. 
This  parameter  is  required. 

Example t 

The  following  example  Illustrates  the  procedure  for  sequential 
sampling.  Five  channels  are  converted  at  gains  of  1,  2,  20,  50,  and 
1000,  starting  at  channel  3. 

C 

C  ALLOCATE  SPACE  FOR  STATUS  ARHAY 

C 

DIMENSION  ISB  (2) 
C 

C  ALLOCATE  SPACE  FOR  CONTROL  ARRAY 
C  AND  ESTABLISH  INITIAL  VALUES 
C 

DIMENSION  IC0NT(5) 

DATA  ICONT(l) ,IC0NT(2) , ICONT (3) /O000003, 0010000,0050000/ 

DATA  IC0NT(4) , IC0NT(5) /OlOOOOO, 0150000/ 
C 

C  ALLOCATE  SPACE  ?0R  DATA  ARRAY 
C 

DIMENSION  IDAT  (5) 


C 

C  INITIATE  SEQUENTIAL.  ASYNCHRONOUS  CONVERSION 

C  VIA  LUN  1 

C 

CALL  AIS0(5, ICONT, IDAT, ISB, 1) 
10       IP(ISB(1) .NE.O)  GO  TO  20 

(continue  processing) 


C 

C  TEST  CONVERSION  STATUS 

C 

GO  TJ   10 
20  (test  for  errors  or   process  converted  data) 


END 
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18. 4.'*  AO/AONt  Analog  Output  -  Multichannel 

This  ISA  standard  routina  la  callad  to  output  voltaga   from  multlpl* 
D/A  channals. 

Calling  Saquancat 

CALL  A0(inm,lcnt,idat[,i8bl [,lun] ) 
or 

CALL  AOWdnm, lent. .  .and  so  forth) 

Argument  Descriptions: 

inm  -  Integer  variable  containing  the  number  of  channels  to 
be  output. 

lent  -  Integer  array  containing  the  channel  numbers  to  receive 
output. 

Idat  -  Integer  array  containing  the  output  voltage  setting  as 
a  value  between  0  and  1023  where: 

0-0  volts  dc  and 

1023  -  +9.99  volts  (full  scale). 

Isb  -  Optional  2-word  integer  array  to  receive  status.  One 
of  the  following  values  is  returned  in  Isb(l).  The 
second  element  is  always  0. 

♦1    -   Function  successfully  completed. 

+3    -  No  channels  requested. 

+4    -   Insufficient  dynamic  storage  to  allocate  an 
I/O  packet. 

4-8    -   LUN  was  not  assigned. 

+99    -   Invalid  LUN. 

+303   -  Controller  not  ready. 

+321   -  Nonexistent  channel  specified. 

lun    -   Integer  variable  containing  the  logical  unit  number. 

Example: 

Output  the  variable  voltages  contained   in   IV(1)   and   IV(2)   to   D/A 
channels  2  and  3,  respectively. 
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C 

C  ALLOCATE  DATA  ARRAY      * 

C 

DIMfcNSION  IV{2) 
C 

C  ALLOCATE  CONTROL  ARRAY 
C 

DIMENSION  ICNT(2) 
C 

C  ALLOCATE  STATUS  ARRAY 
C 

DIMENSION  ISB(2) 
C 

C  INITIALIZE  CONTROL  ARRAY 
C 

DATA  ICNT(l) ,ICNT(2)/2,3/ 


C 

C  PERFORM  A/D  OUTPUT  VIA  LUN  3 

C 

CALL  AOW(2,ICNT,IV,ISB,3) 

IF  (ISB(l) .GE.3)  go  to  error  processor 


18.4.7   DOL/DOLW:  Digital  Output  -  Bistable  Multiple  Fields 

The  following  ISA  standard  call  provides  the  capability  of  latching  or 
unlatching  multiple  16-polnt  bistable  digital  output  fields. 

Calling  Sequence: 

CALL  DOL(inm,icnt,idat,iinskt,lsbl  [,lunl  ) 

or 

CALL  DOLWdnm, lent.  ..and  so  forth) 

Argument  Descriptions: 

inm  -  Integer  variable  specifying  the  number  of  fields  to  be 
latched  or  unlatched. 

lent  -  Integer  array  containing  the  initial  point  within  each 
field. 

idat  -  Integer  array  containing  binary  data  that  defines 
points  within  the  field  to  be  latched  or  unlatched. 
The  state  of  each  bit  is  Interpreted  as  follows: 

1  ■  Latch  point 

0  ■  Unlatch  point 
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Imsk  -  Integer  array  containing  binary  data  that  defines 
points  within  the  field  for  which  a  change  of  state  is 
permitted. 

A  bit  set  to  1  defines  a  point  that  may  assume  the 
state  defined  by  the  corresponding  bit  in  idat.  A  0 
bit  specifies  a  point  for  which  no  change  of  state  Is 
permitted. 

i«b  -  Optional  2-word  integer  array  to  receive  the  results  of 
the  call.  Status  is  returned  in  isb(l)  as  shown  below. 
lsb(2)  is  always  0. 

♦I    -  Function  successfully  completed. 
♦3    -  No  points  specified. 

♦4    -   Insufficient  dynamic  storage  to  allocate  an 
1/0  packet. 

♦I    -   LUN  was  not  assigned. 

+99   -   Invalid  LUN. 

+303   -  Controller  not  ready. 

+321   -  Nonexistent  point  number  specified.   One  or 
more  points  within  the  field  do  not  exist. 

lun     -   Integer  specifying  the  Logical  Unit  Number. 

Example: 

Reset  points  0,1,20  and  21 

DIMENSION  ICNT(2) ,I0AT{2) ,IMSK(2) 
C 

C  INITIALIZE  THE  CONTROL  ARRAY 
C 

DATA  ICNT(l) ,ICNT(2)/0,20/ 
C 

C  INITIALIZE  MASK  ARRAY  TO  EFFECT  A 

C  CHANGE-OF-STATE  ONLY  ON  THE  SPECIFIED 

C  POINTS. 

C 

DATA  IMSK(l) ,IMSK(2)/O000003, 0000003/ 


C 

C  RESET  THE  SPECIFIED  POINTS.   ICR  IS  ASSIGNED 

C  TO  LUN  3. 

C 

CALL  DOLW(2,ICNT,IDAT,IMSK,,3) 
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18.4.8   Dlqital  Input 

Both  of  th«  following  subroutines  pcrtorm  their  funcliori'  through 
direct  access  to  the  ICS/ICR  hardware  registers.  Therefore,  the 
physical  unit  number  replaces  LUN  in  the  calling  sequences  described 
below.  Note  that  any  need  for  conversion  of  BCD  encoded  digital  input 
Into  binary  can  be  accomplished  through  the  FORTRAN  function 

IBIN-KBCD2B  (IBCD). 
Binary  data  can  be  converted  to  BCD  through  the  FORTRAN  function. 

IBCD-KB2BCD  (IBIN). 
The  maximi'm  input  value  for  conversion  is  9999. 

NOTE 

When  the  physical  unit  number  is 
explicitly  included  in  the  calling 
sequence,  it  cannot  be  reassigned  by  the 
MCR  command  ASN. 


18.4.8.1  DI/DIW:  Digital  Input  -  Digital  Sense  Multiple  Fields  -  This 
ISA  standard  subroutine  provides  the  capability  of  reading  multiple 
Ifi-point  digital  sense  fields. 

Calling  Sequence: 

CALL  DI (inm,icnt,idat[,isbl [,iunl) 
or 

CALL  DIW( inm,icnt . . .and  so  forth) 

Argument  Descriptions: 

inm  -  Integer  variable  specifying  the  number  of  fields  to  be 
read . 

icnt  -  Integer  array  containing  the  initial  point  number  of 
each  field. 

idat    -   Integer  army   to  receive  the  input  data. 

isb  Optional,  2-word  integer  array  to  receive  the  results 
of  the  call.  The  status  is  returned  in  isb  (1)  as 
follows: 

+1     -   Function  succesfully  completed. 

+3     -   No  points  requested. 

+321  -  Nonexistent  point  requested.  One  or  more 
points  within  the  16-bit  field  does  not 
exist. 

lun  -  Optional  integer  variable  specifying  the  physical  unit 
number. 
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Exampla : 
"*?J  t)J^  contact  sans*  fialrts  starting  at  points  3  and  27  on   physical 

DIMENSION   ICNT(2),  IDAT ( 2) , ISB ( 2) 
DATA    ICNT(1),ICNT(2)/J,27/ 

CALL  01  (2,ICNT,IDAT,ISB,2) 

IP  (ISB(l) .GE. 3)  go  to  error  procedure 

18.4.8.2  RCIPT:  Digital  Input  -  Oiqltal  Interrupt  Single-Point  -  The 
following  subroutine  returns  the  state  of  a  single  digital  Interrupt 
point  as  a  logical  value. 

Calling  Sequence: 

CALL  RCIPT  (lpt,lsb[,lun] ) 

Argument  Descriptions: 

ipt    -   Integer  variable  defining  the  point  to  be  read. 

isb    -  a  2-word  Integer  array  to  receive  status  and   data   as 
follows.   Status  Is  returned  to  Isb(l). 

♦1  -  Function  successfully  completed.  Data  is 
returned  to  lsb(2)  as  a  logical  value, 
where : 

.•^RUE.   (-1)  =  Point  closed. 

.FALSE.   CO)  =  Point  open. 

+321   -  Nonexistent  point  specified. 


iun 


-  Optional  integer  variable  defining   the   physical   unit 
number. 


Example: 

Read  the  state  of  contact  interrupt  point  3  on  unit  0. 
DIMENSION  ISB  (2) 


CALL  RCIPT  (3,ISB,0) 

IF  (ISB(2) .EQ.. FALSE.)  go  to  point  open  routine. 
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lfl.4.9  DOM/DOMW:  Digital  Output  Momantary  -  Multiple  Plalda 

Thia  ISA  atandard  call  allows  multiple  l^i-blt  fields  to  be  pulsed. 

Calling  Sequencct 

CALL  DOM  (lnm,lcnt,ldat(,ldx)  r,l3b) [,lunl ) 

or 

CALL  DOMW  (inm, lent... and  so  forth) 

Argument  Descriptions; 

iim    -   Integer  variable  specifying  the  number  of  fields  to 
Dulsed . 


lent 


-   Integer  array  containing   the   initial   point   in   each 
field. 

Idat  -  Integer  array  defining  the  points  to  be  pulsed.  A  bit 
is  set  corresponding  to  each  point  that  is  to  be 
triggered  . 

Idx  -  Optional  dummy  integer  variable  retained  for 
compatibility  with  the  standard  form  of  the  call. 

lab  -  Optional  2-word  Integer  array  to  receive  the  results  of 
the  call  as  follows  in  isb(l),  isb(2)  Is  set  to  0. 

+3    -   Number  of  fields  to  be  output  is  0. 

+4    -   Insufficient  dynamic  storage  to  allocate  on 
I/O  packet. 

+8    -   LUN  not  assigned. 

+99   -   Invalid  LUN. 

+303   -  Controller  not  ready 

+321   -  Nonexistent  point  specified.   One  or  more 
points  within  a  field  do  not  exist. 

lun    -   Integer  variable  defining  the  logical  unit  number. 

Example: 

Pulse  momentary  digital  output  fields  defined  by  points  20,  37,  and   0 
on  LUN  1 , 

DIMENSION  IC0NT(3) ,IDAT(3) 

DATA  ICONT(l) ,IC0NT(2) , ICONT ( 3 ) /20, 37 , 0/ 

CALL  D0M(3,IC0NT,IDAT,,1) 
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18.4.10  RTO/RTOWt  R«not«  Terminal  Output 

The  following  function  provides  the  capability  of  transmitting  a 
character  string  to  a  remote  ICRll  terminal.  Both  synchronous  and 
asynchronous  forms  are  supported. 

Calling  Sequence: 

CALL  RTO  (lbc,ldat[,l8bl [,lunl ) 
or 

CALL  RTOW  (ibc,idat....etc.) 

Argument  Descriptions: 

Ibc  -  Integer  vari«ble  specifying  the  number  of  bytes  to 
output. 

Idat  -  Byte  array  (LOGICAL  *  1)  containing  the  character 
string  to  be  output. 

isb  -  Optional,  2-word  integer  array  to  receive  the  results 
of  the  call  in  Isb(l)  as  follows.  Isb(2)  is  set  to  the 
number  of  bytes  actually  transferred  to  the  device. 

0     -  Operation  pending. 

♦1    -  Function  successfully  completed. 

♦3    -  No  bytes  to  be  transmitted. 

♦4  -  Insufficient  dynamic  storage  to  allocate 
I/O  packet. 

♦8    -  Unassigned  LUN. 

■♦•99   -   Invalid  LUN. 

+303  -  Device  not  ready.  Terminal  failed  to 
respond  within  1  second  after  character  was 
transmitted. 

+306  -  Part  or  all  of  buffer  is  out  of  the  issuing 
task's  addressing  space. 

+321   -  Nonexistent  module.   Device  is  ICSll. 

lun    -   Integer  variable  defining  the  logical  unit  number. 

Example: 

Output  a  character  string   to  a   remote   terminal   by  the   ICR  unit 
assigned  to  LUN  3. 

CALL  RTOW (32, 'APPLY  +5  VOLTS  TO  A/D  CHANNEL  10',, 3) 
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18.4.11   Unsolicited  Interrupt  Data  -  Continual  Monltorinq 

Subroutines  are  provided  that  permit  a  FORTRAN  program  to  continually 
monitor  unsolicited  interrupt  data  supplied  to  a  user  circular  buffer, 
as  described  in  Section  18.3.6.  Such  routines  allow  the  program  to 
connect  a  buffer  for  input,  disconnect  the  buffer  upon  completion,  and 
read  and  return  the  buffer  contents  in  a  format  suitable  for  FORTRAN 
processing.  The  calls  summarized  below  perform  these  functions  for 
interrupting  digital  input  modules,  counters,  and  remote  terminal 
inputs: 

Interrupting  Digital  Inputs 

CTDI   -  Connect  a  buffer  to  receive  digital  Interrupts 

RDDI   -   Read  the  state  of  a  single  interrupting  point 

RDCS   -  Read  the  state  of  a  single  interrupting  point  for  which 
a  change  of  state  has  been  detected 

RDWD   -  Read  ifi  bits  of  Interrupt  data  from  the  circular  buffer 

DFDI   -  Disconnect  a  buffer  from  digital  interrupts 

Counter  Modules 

CTTI    -  Connect  a  buffer  to  receive  counter  Interrupts 

RDTI   -  Read  the  counter  circular  buffer 

DFTI    -  Disconnect  a  buffer  from  counter  Interrupts 

Remote  Terminal  Input 

CTTY   -  Connect  a  buffer  to  receive  remote  terminal  inpu^ 
RDTY   -  Read  remote  terminal  data  from  the  circular  buffer 
DFTY   -  Disconnect  a  buffer  from  remote  terminal  Interrupts 


18.4.11.1   CTDI:  Connect  a  Buffer  for  Receiving  Digital  Interrupt  Data 
-  The   following   routine   allows  a  task  to  provide  a  circular  buffer 
that  will  receive  digital  Interrupt  data,  and  to  define  an  event   flag 
that  will  be  set  upon  the  occurrence  of  each  Interrupt. 

Calling  Sequence: 

CALL  CTDI  {ibuf  ,lsz,iev[,isbn,lun]  ) 

Argument  Descriptions: 

Ibuf   -  An  Integer  array  making  up  the  circular  buffer  that   is 
to  receive  interrupt  data. 

isz    -   Integer  variable  specifying  the  length  of  the   circular 
buffer  in  words. 
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l«v  -  Integer  variable  specifying  the  event  flag  that  Is  to 
be  set  whenever  the  driver  receives  an  Interrupt  from  a 
digital  Input  module. 

lab  -  Optional,  2-word  Integer  array  to  receive  the  results 
of  the  call.  The  status  values  specified  below  are 
returned  to  isb( 1) . 

+1  -  Function  successfully  completed.  isb(2) 
receives  the  number  of  words  passed  per 
Interrupt  in  the  low  byte. 

+4  -  Insufficient  dynamic  storage  to  allocate  an 
I/O  packet. 

+8    -  Unasslgned  LUN. 

+99    -   Invalid  LUN. 

+30fi  -  Par*-  of  buffer  Is  out  of  the  user's  address 
spat  3  or  buffer  is  too  small  to  accommodate 
a  single  entry. 

+316  -  Privilege  violation  -  task  is  check- 
pointable and  not  fixed  in  memory. 

+319  -  Buffer  address  or  length  is  an  odd  number 
of  bytes. 

+322  -  Another  task  is  already  connected  to 
Interrupts. 

+397   -   Invalid  event  flag  specified. 

lun    -   Integer  variable  specifying  the  logical  unit  number. 

The  space  allocated  for  the  circular  buffer  must  be  large  enough  to 
accommodate  at  least  one  5-word  entry  plus  an  additional  10  words  of 
storage  that  are  required  by  the  subroutines  that  read  circular  buffer 
contents.  Thus,  the  buffer  allocation  specified  by  the  Integer 
variable  isz  may  be  computed  as 

isz  =  (10  +  5  *  n) 


n 


isz 


The  number  of  entries  to  be  contained  in  the  buffer, 


Expressed  in  words. 


IR.4.11.2  Reading  Digital  Interrupt  Data  -  Each  of   the  following 

routines   reads  data   that  has  been  stored  in  the  circular  buffer  and 
performs  the  following  common  processing: 

1.   Detects,  and  optionally  reports,  the  occurrence  of  an   error 

entry  that  has  been  placed  in  the  buffer  by  the  driver 
because  of  a  nonrecoverable  device  fault  (for  example,  fatal 
serial  line  error  or  remote  power-fail). 
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2.  Clears  the  trigger  event  flag  when  no  further  entries   remain 
to  be  processed. 

3.  Clears  and  optionally  reports  any  overrun  conditions. 

Only  one  of  the  following  three  routines  can  be  invoked   by   a   single 
task : 

1.   RDDI:   Read  Digital  Interrupt  Data  from  a  Circular  Buffer 

The  RDDI  FORTRAN  subroutine  reads  contact  interrupt  data  from 
a  circular  buffer  that  was  specified  in  a  CTDI  call  (see 
lR.4.n.l).  It  does  no  actual  input  or  output,  but  rather 
performs  a  point-by-point  scan  of  an  Interrupt  entry  in  the 
buffer,  returning  the  state  of  each  point  as  a  logical  value. 

On  the  Initial  call  to  RDDI,  the  module  number  and  data  of 
the  next  Interrupt  entry  are  read  from  the  circular  buffer 
and  stored  for  subsequent  reference.  The  subroutine  then 
sets  the  current  data  bit  number  n  to  0,  examines  the  state 
of  data  bit  n,  and  converts  bit  n  to  a  point  number  by  the 
following  formula: 

ipt  ■  module  number  *  16  +  n 


On  each  subsequent  call,  n  is  incremented  by  one  and  then 
data-bit  n  Is  examined  in  the  stored  module  iata.  When  n 
reaches  \fi,  it  Is  reset  to  0  and  an  attempt  is  made  to  read 
the  next  interrupt  entry  from  the  circular  buffer.  If  a 
valid  entry  is  not  found,  ipt  is  set  negative  and  let  (if 
specified)  Is  either  assigned  a  value  of  0  or  an  overrun 
count  that  is  maintained  by  the  IC3/ICR  driver.  If  let  is  0, 
no  further  entries  remain.  A  nonzero  value  indicates  that 
the  driver  received  more  data  than  could  be  stored  in  the 
buffer,  and  let  represents  the  number  of  entries  that  were 
discarded . 


The  variable  let  receives  the  control  register  contents  that 
are  set  by  the  driver  --  as  described  in  Section 
18.3.fi  —  whenever  a  nonrecoverable  controller  error  occurs. 


Calling  Sequence: 

CALL  RDDI  (ipt,ival[,ict] ) 

Argument  Descriptions: 


ipt     -  A  variable  to   which   the   digital   input   point 
number  is  returned.   It  may  be  set  as  follows: 

1.  Ipt   0  if  nc   -lid  entry  is  found 

The  specific  value  of   ipt   reflects   the   error 
that  was  detected  as  follows: 

-1  -  no  data   (that   is,   no   Interrupt   data 
currently  in  buffer) 

-2  -  overrun 

-3  -  hardware  error 

2.  ipt  =>  0  if  the  value  indicated  is   a   point 
number;   the  state  is  returned  to  ival. 
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ival  A  variable  to  whl'  h  the  state  of  the  pent  Is 
returned;   It  may  be  set  «s  follows: 

1.  .FALSE.   (0)  if  the  point  is  open 

2.  .TRUE.   (-1)  if  the  point  is  closed 

let  -  Optional  integer  variable  to  receive  the  overrun 
count  or  the  contents  of  the  CSR  register  on  the 
occurrence  of  a  fatal  controller  error. 
Otherwise,  set  to  0. 

NOTE 

A  task   reading   the  circular   buffer 
should   not   issue   a  Wait-For  directive 
'  jntil   a   buffer-empty   condition    is 

reported.  See  Section  18.4.11.11  for  an 
example  of  how  to  read  circular-buffer 
entries. 

f 

I  2.   RDCS:   Read  Digital  Interrupt  Points  That  Have  Changed  State 

\                                                    The  RDCS  FORTRAN  subroutine  returns  data   in   the   format  of 

subroutine   RDDI  —   as  described  above  —  except  that  only 

points  that  have  changed  state  are  processed,   resulting   in 

significantly  improved  throughput  and  reduced  processing 
overhead  for  the  calling  task. 

Processing  specific  to  the  routine  is  as  follows: 

On  the  initial  call,  the  module  number,  module  data,  and 
change  of  state  Information  are  read  from  the  circular  buffer 
and  stored  for  later  reference.  The  subroutine  then  sets  the 
current  data  bit  number  n  to  0  and  begins  scanning  the 
change-of-state  word  until  a  nonzero  bit  is  found.  The  point 
number  and  current  state  are  then  reported  as  previously 
described.  If  no  change  of  state  Is  found  or  when  no  further 
bits  remain  to  be  processed,  the  next  entry  is  fetched  as 
described  above. 

The  processing  of  error  conditions  Is  Identical  to  subroutine 
RDDI. 

It 

Calling  Sequence: 

CALL  RDCS  (Ipt, Ival [, let] ) 

Argument  Descriptions: 

ipt  -  Integer  variable  to  receive  the  digital  input 
point  number.   It  may  be  set  as  follows: 

1.   ipt  0  if  no  valid  entry  ir  found   (that   is, 

overrun,  error,  or  no  data  in  buffer).   The 

specific  value  of   Ipt   reflects   the   error 

that  was  detected  as  follows: 

-1  -  no  data 
-2  -  overrun 
-3  -  hardware  error 
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2.   Ipt  ->  0  If  the  value  Indicated  is   a   point 
number,  the  state  is  returned  to  Ivali  . 

ivdl  -  Integer  variable  to  receive  the  state  tf  the 
point  as  a  logical  value  where: 

1.  .FALSE.   (0)  -  Point  open 

2.  .TRUE.   (-1)  -  Point  closed 

let  -  Optional  integer  variable.  A  nonzero  value 
indicates  that  the  variable  has  been  set  with  an 
overrun  count  returned  by  the  driver,  or  with 
the  contents  of  the  CRR  register  on  the 
occurrence  of  a  fatal  controller  error. 
Otherwise,  set  to  0. 


NOTE 

A  task  reading  the  clrcula,.'  buiter 
should  not  Issue  a  Wait-For  directive 
until  a  buffer-empty  condition  Is 
reported.  See  Section  18.4.11.11  for  an 
example  of  how  to  read  circular-buffer 
entries. 


3.   RDWD:   Read  a  Full  Word  of  Digital  Interrupt  Data 

The  following  subroutine  is  cal  ed  to  return  a  full  word  of 
digital  Interrupt  data  from  che  circular  buffer,  and 
optionally  change  of  state  information.  A  new  entry  is  read 
for  each  call;  hence,  throughput  is  hJjh  when  processing  Is 
contingent  upon  several  possible  conditions  within  a  module. 

Calling  Sequence: 

CALL  RDWD  ( 5mod  ,  i val f , let]  [ ,  Icos] ) 

Argument  Descriptions: 

Imod   -   Integer  variable  to  receive  the  module  number  or 
status  as  follows: 

1.  imod  0  if  no  data  is  present  or   an  overrun 
condition  or  error  was  detected 

The  specific  value  of  ipt  reflects  the  error 
that  was  detectec!  as  follows: 

-1  -  no  data 
-2  -  overrun 
-3  -  hardware  error 

2.  imod  =>  0  Module  number.   Interrupt  data   is 
in  ival 

ival   -   Integer  variable   to    receive   the   digital 
interrupt  data. 
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let  -  Optional  integer  variable.  A  nonzero  value 
Indicates  that  the  variable  has  been  set  with  an 
overrun  count  returned  by  the  driver,  or  with 
the  contents  of  the  CSR  register  on  the 
occurrence  of  a  fatal  error.  Otherwise,  set  to 
0. 

Icos  -  Optional  Integer  variable  to  receive 
change-of-state  information.  Bits  set  to  a  1 
correspond  to  points  for  which  a  change  of  state 
has  been  recorded. 


NOTE 

A  task  reading  the  circular  buffer 
should  not  issue  a  Walt-For  directive 
until  a  buffer-empty  condition  is 
reported.  See  Section  18.4.11.11  for  an 
example  of  how  to  read  circular-buffer 
entries. 


18.4.11.3  DFDI :  Disconnect  a  Buffer  from  Digital  Interrupts  -  The 
following  routine  is  called  to  disconnect  a  task's  circular  buffer 
from  digital  interrupts. 

Calling  Sequence: 

CALL  DFDI  (flsbl [,lunl ) 

Argument  Descriptions: 

lib    -  Optional  2-word  Integer  array  to  receive  the  results  of 
the  call  as  follows.   isb(2)  is  always  0. 

■fl    -  Function  successfully  completed 

+4    -   Insufficient  dynamic   storage   to   allocate 
I/O  packet. 

+8    -  Unasslgned  LUN. 

+99   -   Invalid  LUN. 

+322   -  Task  not  connected  to  Interrupts. 

lun     -   Integer  variable  containing  logical  unit  number. 


18.4.11.4   CTTI :   Connect   a  Buffer   for  Receiving  Counter  Data  -  The 

following  subroutine  may  be  called  to  connect  a  circular  buffer  that 
is  to  receive  counter  data,  and  to  define  an  event  flag  that  is  to  be 
set  upon  occurrence  of  each  interrupt. 

Calling  Sequence: 

CALL  CTTI  (ibuf ,isz,lev, ivf , isb]  [  ,lunl ) 
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Argument  Descr ipt ionsi 

Ibuf  -  An  Integer  array  making  up  the  circular  buffer  that  Is 
to  receive  interrupt  da. a. 

Isz  -  Integer  variable  specifying  the  length  of  the  circular 
buffer  in  words. 

lev  -  Integer  variable  defining  an  event  flag  that  is  to  be 
set  whenever  the  driver  receives  an  Interrupt  from  a 
counter  module. 

Iv  -  Integer  array  of  initial  counter  values.  One  element 
is  required  for  each  counter  In  the  physical  unit.  The 
value  is  used  to  initialize  and  reset  the  counter  when 
a  value  of  0  is  reached.  This  parameter  may  be  reset 
for  a  specific  module  through  a  call  to  SCTI. 

Isb  -  Optional  2-word  integer  array  to  receive  the  results  of 
the  call.  The  status  values  specified  below  are 
returned  to  lsb{l) . 

+1  -  Function  successfully  completed.  tsb(2) 
receives  the  number  of  words  passed  per 
Interrupt  in  the  low  byte. 

+4  -  Insufficient  dynamic  storage  to  allocate  an 
I/O  packet. 

+8     -   Unassigned  LUN. 

+99    -   Invalid  LUN. 

+303   -   Controller  not  ready. 

+306  -  Part  of  buffer  is  out  of  the  user's  address 
space  or  buffer  is  too  small  to  accommodate 
a  single  entry. 

+316  -  Privilege  violation  —  task  is 
checkpointable  and  not  fixed  In  memory. 

+319  -  Buffer  address  or  length  Is  an  odd  number 
of  bytes. 

+322  -  Another  task  Is  already  connected  to 
Interrupts, 

+397   -   Invalid  event  flag  specified. 

lun    -   Integer  variable  specifying  the  logical  unit  number. 

The  space  allocated  for  the  circular  buffer  m'st  be  large  enough  to 
accommodate  at  least  one  4-word  entry  plus  jn  additional  8  words  of 
storage  required  by  the  subroutine  that  reads  buffer  contents  (RDTI). 
The  buffer  allocation  specified  by  the  variable  Isz  may  be  computed  as 

isz  =  (8  +  4  *  n) 


n 

The  number  of  entries  to  be  contained  In  the  buffer. 
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NOTE 

A  task  reading  the  circular  buff»?r 
should  not  issue  a  Walt-For  directive 
until  a  buffer-empty  condition  is 
reported.  See  Section  18.4.11.11  for  an 
example  of  how  to  read  circular-buffer 
entries. 


18.4.11.5  RDTI:  Read  Counter  Data  from  the  Circular  Buffer  -  The 
following  call  returns  counter  interrupt  data  from  the  circular 
buffer.   A  new  entry  is  read  on  each  call. 

Calling  Sequence: 

CALL  RDTI  (imod,ival[,ict]) 

Argument  Descriptions: 

imod  -  Integer  variable  to  receive  module  number  and  status  as 
follows: 

1.  imod  0  No  data  In  buffer,  dat'^  overrun  or  error 
condition  detected  The  specific  value  of  ipt 
reflects  the  error  that  was  detected  as  follows: 

-1  -  no  data 
-  2  -  overrun 
-3  -   hardware  error 

2.  imod  =>  0  Module  number  of  counter.  Interrupt  data 
is  in  ival. 

Ival  -  Integer  variable  to  receive  the  counter  data  at 
interrupt. 

let  -  Optional  Integer  variable  to  receive  the  overrun  count, 
or  the  ICSR  contents  returned  by  the  driver  on  the 
occurrence  of  a  fatal  hardware  error.  Otherwise,  set 
to  0. 


NOTE 

A  task  reading  the  circular  buffer  should  not 
issue  a  Walt-For  directive  until  a  buffer-empty 
condition  is  reported.  See  Section  18.4.11.11 
for  an  example  of  how  to  read  circular-buffer 
entries. 


18.4.11.6  Miscellaneous  Counter  Routines 


RSTI:   Read  a  Counter  Module 

The  following  routine  directly  accesses  a  counter  register  to 
return  Its  current  value. 
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Calling  Sequence i 

CALL  RSTI  (imocl,lsb[,lun]  ) 

Argument  Descriptions: 

Imod    -  An  integer  variable  containing  the  number  of  the 
counter  to  be  read. 

Isb  ,  -  A  2-word  integer  array  to   receive   status  and 
data  as  follows.   Status  is  returned  to  isb(l). 

♦1    -   Function   successfully   completed. 
Data  is  returned  to  isb(2). 

+321   -  Nonexistent  module  specified. 

lun    -  Optional  integer  variable  specifying  the  ICS/ICR 
physical  unit  number. 

2.   SCTI:   Reset  a  Counter  Initial  Value 

The  following  routine  may  be  called  by  any  task  to  revise  the 
initial  value  that  is  used  to  activate  a  counter. 

Calling  Sequence: 

CALL  SCTI  (imod,lvair ,Isb]  [,lun] ) 

Argument  Descriptions: 


imod 


-   Integer  variable  specifying  the  relative  module 
number  of  the  counter  to  be  reset. 


ival    -   Integer  value  specifying  the  new  Initial  value. 

isb    -  Optional  2-word  integer  array  to  receive   status 
as  follows.   lsb(2)  is  always  0. 

+1    -   Function  successfully  completed 

+4    -   Insufficient  dynamic   storage   to 
allocate  an  I/O  packet 

+8    -   Unassigned  LUN 

+99   -   Invalid  LUN 

+303   -   Controller  not  ready 

+321   -   Nonexistent  module  specified 

lun    -   Integer  specifying  the  logical  unit  number. 


The 


18.4.11.7  DFTI:  Disconnect  a  Buffer  from  Counter  Interrupts  -  i,,^- 
followlng  subroutine  is  called  to  disconnect  the  task's  circular 
buffer  from  interrupts. 

Calling  Sequence: 

CALL  DFTI  (fisb]  r,lunl ) 
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Argument  Descriptions: 

lab    -  Optional  2-word  Integer   array   to   receive  status  as 
follows.   Isb(P)  Is  always  0. 

♦X    -   Function  successfully  completed. 

♦4    -   Insufficient  dynamic  storage  to  allocate  an 
I/O  packet. 

♦•    -   Unasslgned  LUN. 

+99   -   Invalid  LUN. 

+322   -  Task  was  not  connected  to  interrupts. 

%Vm  -      Integer  variable  specifying  the  logical  unit  number. 


18.4.11.8  CTTY:  Connect  a  Circular  Buffer  to  Terminal  Interrupts  -  The 
following  routine  allows  a  task  to  provide  a  circular  buffer  to 
receive  remote  terminal  input  data,  and  to  define  an  event  flag  that 
is  set  on  the  occurrence  of  each  interrupt. 

Calling  Sequence: 

CALL  CTTY  ( ibuf , isz , lev ( , isb]  F  ,lun] ) 

Argument  Descriptions: 

The  following  arguments  are  identical  in  form  and  function  to  those 
described  for  subroutine  CTDI  (see  Section  18.4.11.1): 

ibuf  -  An  integer  array  making  up  the  circular  buffer  that 
receives  interrupt  data 

isz    -   Length  of  the  circular  buffer  in  words 

lev    -   Event  flag  to  be  set  on  each  terminal  interrupt 

Buffer  size  is  computed  as 

isz  =  (8  +  4  *  n) 

n 

The  number  of  entries  that  can  be  storeci  in  the  buffer. 

isb  -  Optional  2-word  integer  array  to  receive  the  results  of 
the  call.  The  status  values  specified  below  are 
returned  to  isb(l)  . 

+1  -  Function  successfully  completed.  isb(2) 
receives  the  number  of  words  passed  per 
interrupt  in  the  low  byte. 

+4  -  Insufficient  dynamic  storage  to  allocate  an 
I/O  packet. 

+8    -   Unassigned  LUN. 

+99    -   Invalid  LUN. 
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+306  -  Part  of  buffer  is  out  of  the  user's  address 
space  or  buffer  is  too  small  to  accommodate 
a  single  entry. 

+316  -  Privilege  violation  —  task  is 
checkpointable  and  not  fixed  in  memory. 

+  319  -  Buffer  addr^^ss  not  on  a  word  boundary  or 
length  is  an  odd  niiiribfr  of  bytes. 

+321  -  Nonexistent  module  specified.  Unit  is 
ICSll. 

* 

+322  -  Another  task  is  already  connected  to 
Interrupt. 

*397   -   Invalid  event  flag  /specified. 
Logical  u.iit  number. 


18.4.11.9  RDTY:  Read  a  Character  from  the  Terminal  Buffer  -  This 
subroutine  retrieves  a  single  character  from  the  terminal  circular 
buffer  on  each  call. 

Calling  Sequence: 

CALL  RDTY  ( ind , ichr [ , i vr ] ) 

Argument  Descriptions: 

ind    -   An  integer  variable  to  receive  status  as  follows: 

1.  =0  character  retrieved  from  buffer  is  in  ichr 

2.  <0  no  data  in  buffer,  overrun,  or  hardware  error 

The  specific  value  of  ind  reflects  the   error   that 
was  detected  as  follows: 

-1  -  no  data 
-2  -  overrun 
-3  -  hardware  error 

ichr  -  Logical  *  1  or  integer  variable  to  receive  the  terminal 
data.  If  an  integer  is  specified,  only  the  low  byte 
will  be  set. 

ivr  -  Optional  integer  variable  to  leceive  the  overrun  count, 
or  the  ICSR  contents  on  the  occurrence  of  a  fatal 
hardware  error.   Otherwise,  set  to  0. 

NOTE 

A  task  reading  the  circular  buffer   should   not 
issue  a  Wait-For  directive  until  a  buffer-empty 
condition  is  reported.   See  Section   18.4.21.11 
for   an   example  of  how  to  read  circular-buffer   "^ 
-_  .        entries. 
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18.4.11.10  DFTif:  Disconnect  a  Circular  Buffer  from  Terirlnal  Input  - 
The  following  routine  disconnects  a  task's  circular  buffer  from 
terminal  inputs. 

Calling  Sequence: 

CALL  DFTY  (fisb] [,lunl) 

Argument  Descriptions; 

isb    -  Optional,  2-word  integer  array  to   receive   status   in 
isb(l)  as  follows.   isb(2)  is  always  set  to  0. 

•         +1     -   Function  successfully  completed. 

+4    -   Insufficient  dynamic  storage  to  allocate  an 
I/O  packet. 

+8    -  Unassigned  LUN. 

+99    -  Invalid  LUN. 

+322   -  Task  was  not  connected  to  interrupts. 

lun    -  An  integer  specifying  the  logical  unit  number. 


18.4.11.11  Programming  Example  -  The  following  are  excerpts  from  a 
FORTRAN  program  that  is  to  monitor  a  remote  terminal  for  input  and 
echo  the  received  characters  when  a  carriage  return  is  detected. 

G 

C     SPECIFY  BYTE  FORMAT  FOR  TERMINAL  DATA 
C 

L0GICAL*1  TCHR 
C 

C     Ai-LOCATE  STORAGE  FOR  THE  TERMINAL 
"     C     -.UFFER 
C 

DIMENSION  IBUF(32) 
C 

C     ALLOCATE  STORAGE  FOR  THE  PACKED 
C     INPUT  DATA  SO  THAT  IT  IS  ALIGNED 
C     ON  A  WORD  BOUNDARY 
C 

DIMENSION  ICHR(40) 

DIMENSION  TCHR{80) 

EQUIVALENCE  (TCHR,ICHR) 
C 

C     ALLOCATE  STORAGE  FOR  A 
C     2-WORD  STATUS  BLOCK 
C 

DIMENSION  ISB(2) 
C 

C     INITIALIZE  ICRll  LOGICAL  UNIT{7)  AND 
C     TRIGGER  EVENT  FLAG  NUMBER (2) 


C 


DATA  lEV,  LUN/2,  7/ 
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C 

C     CONNECi  THE  TASK  TO  TERMINAL 

C     INPUTS.  IF  CONNECT  FAILS— STOP  1 

C 

CALL  CTTY  (IBUF, 32, lEV, ISB, LUN) 
IF  (ISB(l) .GE.3)  STOP  1 
C 

C  10— POLL  THE  CIRCULAR  BUFFER 
C'        FOR  DATA.  ECHO  THE  LINE  WHEN 
■C   V      80  CHARACTERS  ARE  RECEIVED 
.  "C         OR  A  CARRIAGE  RETURN  IS 
G         DETECTED. 
•C  '. 

10    DO  70  I  =  1,80 
C 

C     20— WAIT  FOR  TRIGGER  EVENT  FLAG 
C 

20  CALL  WAITFR  (lEV) 

C 

C  30— PACK  THE  CIRCULAR  BUFFER  DATA 

C         INTO  THE  BYTE  ARRAY 

C 

30    CALL  RDTY  (ISB,TCHR ( I ) ,  IVR) 
C 

C     DISPATCH  ON  ERROR  CONDITION 
C 

GO  TO  (20,50,40)-ISB 
GO  TO  60 
C 

C     40— REPORT  HARDWARE  FAULT 

C 

40    CALL  ALARM  (IVR) 


GO  TO  30    '  ,  ;, 
C 

C     50— REPORT  OVERRUN  CONDITION 
C 

50    CALL  LOST  (IVR) 


GO  TO  30 
C 

C  60— CHECK  FOR  CARRIAGE  RETURN, 

C         EXIT  TO  ECHO  ROUTINE  IF 

C         PRESENT 

C 

60  IF  (TCHR(I) .EQ.-IS)  GO  TO  80 

70    CONTINUF 
C 

C     80— FALL  THROUGH  TO  ECHO  A  LINE 
C 

CALL  RTOW  (I,TCHR,,LUN) 
C 
C     DISCONNECT  TERMINAL  BUFFER,  EXIT 


C 


CALL  DFTV  (,LUN) 

CALL  EXIT 

END 
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The  procedure  for  reading  the  buffer   in   the  example  above  may  be 
summarized  as  follows: 

1.  Wait  for  the  trigger  e^^ent  flag  specified  in  the  call  to 
connect  the  buffer. 

2.  Upon  regaining  control,  call  the  appropriate  routine  to  read 
the  buffer  until  one  of  the  following  terminal  conditions  is 
detected : 

a.  All  Jata  has  been  read. 

b.  An  overrun  count  is  detected.  : 

'        c.   A  fatal  error  is  encountered. 

'■'•'' ,  ■    ■•",,'  ■,';■; '  .,  .i  ''■)■ 

3.  On  the  occurrence  of  2a  or  2b,  perform  any  appropriate 
processing;   then  return  to  scan  for  additional  data. 

4.  If  a  hardware  error  is  detected,  use  the  ICSR  register 
contents  for  further  fault  analysis  and  warning  as 
appropriate.   In  the  event  of  such  an  error,  the   event   flag 

i'    will   not  he   set  by  the  driver  again  unless  normal  service  is 
resumed. 

5.  A  calling  task  should   not  execute   the  Wait-For  directive  r 
until   a  buffer-empty  condition  is  detected.   This  is  because 
the  user's  buffer  pointer  is  advanced   after  detecting   and 
clearing   an  overrun  condition,  and  the  trigger-event  flag  is 
cleared  only  when  a  buffer-empty  condition  is  detected. 


18.4.12   Unsolicited  Interrupt  Processing  -  Task  Activation 

The  following  routines  provide  the  capability  of  linking  a  task  to  an 
interrupt,  soliciting  information  from  the  driver  concerning  hew  the 
task  was  activated,  and  unlinking  a  task  from  all  interrupts. 


18.4.12.1   LNK:   Link  a  Task  to  Interrupts  -  This  subroutine   allows 

any   installed   task   to   be  activated   on   the  occurrence   of  any 
unsolicited  interr'<pt. 

Calling  Sequence:  ■       '         "  '**'•,  "^^'J  -•."  ''i  y  ^'  ^     ' .?a.' ":  ■  .'■"' 

CALL  LNK  (tnam,iprm[,isb]  [,lun]  )    '  'i  ,  ,  :  '        "'   ,  ' 


,'  ■  *  • 
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Argument  Descriptions: 

t"^""      -    Real  variable  containing   task   name   in   RADIX-50 
format. 

^P"^""      -    A  5-word  integer  array  containing   the   following 
data : 

Iprri(l)    -    Interrupt  class.   May  be  one  of  the  following: 

0  -  Digital  interrupts 

,._•■■'„'■',  1  -  Counters  •""■.-■-'■ 

2  -  Remote  terminal  (CTRL/C  only) 

3  -  Error  interrupts  ' 

iprm(2)    -    Reserved.  .        ;   ;   . 

iprm(3)    -    Optional  event  flag  set  if  task  to  be  activated  is 
not  dormant  when  the  interrupt  occurs. 

iprm(4)    -    Hardware-dependent  parameters  as  follows: 
iprm(5) 

Interrupt  Class         Parameter  Contents 

Diaital       iprm(4)  =  Point  number 

iprm(5)  =  Change-of-state  mask 

Counter       iprm(4)  =  Module  number 

'      iprm(5)  =  Counter  initial  value 

Remote  Terminal    iprm(4)  =  not  used 

iprm{5)  =  not  used 

Error        iprm(4)  =  not  used 
iprm(5)  =  not  used 

^^^  -  Optional  2-word  integer  array  to  receive  status  in 

isb(l)  as  follows.   isb{2)  is  always  set  to  0. 

+1     -   Function  successfully  completed. 

+3     -   Unrecognized       interrupt      class 
specified. 

+4     -   Insufficient    dynamic    storage     to 
allocate  I/O  packet. 

+8     -   Unassigned  LUN. 

+99    -   Invalid  LUN. 

+301   -  Task  tnam  not  installed. 
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+303   -  Controller  not  ready. 

^  +317   -  Resource  in  use.   Other   task  already 

linked  to  interrupt. 

+323   -   Insufficient   dynamic    memory    to 
allocate  secondary  control  block. 

y     .  ;  :>  ;\     ■  +380   -   Task  tnam  not  installed. 

+397   -   Invalid  event  flag  number  specified. 

lun       -    Optional   integer   specifying   the   logical    unit 
number  ^ 

Example: 

Link  task  ALARM   to   report   fatal   hardware  errors  arising   from  a 
malfunction  on  any  ICRll  physical  unit.  . 

blMENSION  IPRM(5)   .  , 

C 

C   INITIALIZE  PARAMETER  ARRAY  WITH: 

C     1.   INTERRUPT  CLAFS 

C     2.   RESERVED  ELEMENT  CLEARED 

C     3.   GLOBAL  EVENT  FLAG   ' 

c  '•_■.,';■■ 

DATA  IPRM(l),  IPRM(2),  IPRM ( 3 ) /3 , 0 , 64/ 
DATA  ALARM/6RALARM  / 


CALL  LNK  (ALARM, IPRM, ,7) 


?',4.12.2  RDACT:  Read  Activation  Data  -  The  following  call  allows  a 
t,.3k  to  determine  the  interrupt  conditions  that  caused  it  to  oecome 
active. 

Calling  Sequence: 

CALL  RDACT  ( iprm [ , isb]  f , lunl ) 

Argument  descriptions: 

iprm      -    A  6-word  integer  array  to  receive  activation  data 
in  the  following  format. 

iprm(l)    -    Activation  indicator  (see  Section  18.3.7.5). 

iprm(2)    -    Physical  unit  number  of  ICR. 
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iprm(3)    -    Generic  code.   Set  to  one  of  the  following  values: 
-  •<>       -  Remote  terminal 
1,2,3   -  Digital  interrupt 
4,5,6    -  Counter  interrupt 
177770   -  Fatal  hardware  error 

l.Jrm(4)    -    Relative  module  number. 

iprm(5)    -    Hardware-dependent  data. 
iprm(6) 

The  following  data  is   returned   based   upon   the   type  of   interrupt 
module: 

Generic 
Module  Type      Code  Parameter  Contents 

Remote  Terminal     0         iprm(5)  =  terminal  input  character 

iprm(6)  =  undefined 

Digital  Interrupt    1,2,3     iprm(5)  =  module  data 

iprm{f5)  =  change-of-state  data 

Counter  4,5,6     iprm(5)  =  value  of  the  counter  at 

interrupt 
iprm(6)  =  undefined 

^'^'^o^  177770     iprm(5)  =  contents  of  ICSR 

iprm(6)  =  contents  of  ICAR. 

isb    -  Optional  2-word  integer   array  to   receive   status   in 
isbC   as  follows.   isb(2)  is  set  to  0. 

+i     -   Function  successfully  completed. 

+4    -   Insufficient  iynamic   storage   to   allocate 
I/O  packet, 

+8    -   Unassigned  LUN. 

+99    -   Invalid  LUN. 

T  ii-'i        —         i  Mt  !!!     <i  r  r  n  y        nnf         f  II  i   i  V        wi  rn  i  n        th"?        f  acjjr  •  cs 

addressing  space. 
+319   -   Address  of  iprni  is  odd. 
+379   -  Task  not  linked  to  ICS/ICR  interrupts, 
lun    -   Integer  variable  specifying  the  logical  unit  number. 
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Example: 

The  following  Is  an  excerpt  from  a  program  that  reads  activating  data 
into  array  TACT  and  conditionally  exits  if  the  event  flag  (lEFN) 
specified  in  a  previous  link  request,  issued  by  another  task,  is  not 
set. 

C 

C     ALLOCATE  SPACE  FOR  DATA  ARRAY 


C 


DIMENSION  IACT(6) 


10    CALL  RDACT  (IACT,,7) 


C 

C     CLOSE  ALL  FILES 

C 

CALL  CLOSE(l) 

CALL  CL0SE(2) 
C 

C     EXIT  IF  TRIGG- R  EVENT  FLAG  IS  NOT  SET 
C     ELSE  CLEAR  EVENT  FLAG  AND  RESTART. 
C 

CALL  EXITIF  (lEFN) 
C 

C     FLAG  WAS  SET.   CLEAR  IT  AND 
C     CONTINUE. 
C 

CALL  CLREF  (lEFN) 

GO  TO  10 

STOP 

END 


The  foregoing  example  illustrates  the  following  considerations  when   a 
task  is  made  active  by  ICS/ICR  interrupts: 

1.  To  avoid  race  conditions,  the  Exit-If  directive  should  be 
used  to  test  the  state  cf  the  event  flag  and  conditionally 
exit.  Issuing  a  Test  Event  Flag  directive  followed  by  an 
Exit  v'ould  cause  a  flag  set  condition  occurring  after  the 
test  to  go  unrecognized. 

2,  Use  of  the  Exit-If  directive  bypasses  the  closure  of  ?11 
files  that  is  normally  done  automatically  by  the  FORTRAN 
object  time  system  when  the  program  executes  a  STOP  or  CALL 
EXIT  statement.  Thus,  to  exit  cleanly,  the  program  must 
explicitly  close  all  files  before  invoking  the  directive. 


18.4.12.3  UNLNK:   Remove  Interrupt  Linkage  to  a  Task  -  The   following 
call  removes  all  link(»ge  between  a  task  and  ICS/ICR  interrupts. 


18-68 


INDUSTRIAL  CONTROL  SUBSYSTCMS 

Calling  Sequence: 

CALL  UNLNK  ( tn«m, iprm [ , i sb] [ , lun] ) 

Argument  Descriptions;  '' 

tnam   -  Real  variable  containing  task  name  in  Radix-50  format. 

iprm   -   Integer  variable  containing  the  interrupt   class.    May 
be  one  of  the  following: 

0  -  Digital  interrupts 

1  -  Counters 

2  -  Remote  terminal 

3  "  Error  interrupts 

4  -  All  interrupts 

Isb    -  Optional,  2-word  integer  array  to  receive   the   results 
of  the  call  in  isb(l)  as  follows.   isb(2)  is  set  to  0. 

+1    -  Function  successfully  completed. 

+4    -   Insufficient  dynamic  storage  to  allocate  an 
I/O  packet. 

+8  -   Unassigned  LUN. 

+99  -   Invalid  LUN. 

+379  -  Task  not  linked  to  ICS/ICR  interrupts. 

+380  -   Task  not  installed, 

lun    -   Integer  variable  specifying  the  logical  unit  number. 

Example: 

Remove  the  linkage  between  task  ALARM  and  all  ICS/ICR  interrupts. 
DATA  ALARM/6RALARM  / 
CALL  UNLNK  (ALARM,,,?) 

18.4.13  Maintenance  Functions 

The  following  functions  cause  the  ICS/ICR  driver  to  suppress  or  enable 
hardware  error  reporting  while  on-line  maintenance  and  troubleshooting 
is  in  progress,  as  described  In  Section  18.3.9. 

OFLIN   -   Place  selected  unit  off  line. 

-■.^--        ONLIN   -  Return  selected  unit  to  on-line  status. 

These  calls  may  be  issued  only  by  a  privileged  task. 
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18.4.13.1  OPLIN:  Pl»ce  Selected  Unit  in  Offline  Status  -  The  following 
call  is  executed  to  set  a  controller  off  line: 

CALL  OFLIN  ([isb]  t,lun]) 

Argument  Descriptions: 

isb    -  Optional  2-word  integer  array  to  receive  the  results  of 
the  call  in  isb(l)  as  follows.   isb(2)  is  always  0. 

+1    -  Function  successfully  completed. 

+4    -   Insufficient  dynamic  storage  to  allocate  an 
I/O  packet. 

+8  -  LUN  not  assigned. 

♦99  -  Invalid  LUN. 

+316  -  Issuing  task  not  privileged. 

'  +380  -  Device  already  off  line. 

;  Uttir    -  Integer  variable  specifying  the   ICS/ICR  logical   unit 
'       number. 


18.4.13.2   ONLIN:   Return  a  Device  to  On-line  Status  -  The   following 
call  will  return  the  selected  unit  to  on-line  status. 

CALL  ONLIN  ([isb]  [,lun])  "' 

Argument  Descriptions:  „ 

isb    -  Optional  2-word  integer  array  to  receive  the  results  of 
the  call  in  isb(l)  as  follows.   isb(2)  is  always  0. 

+1    -  Function  successfully  completed. 

+4    -   Insufficient  dynamic  storage  to  allocate  an 
I/O  packet. 

*8    -   LUN  not  assigned. 

+99    -   Invalid  LUN. 

+316   -   Issuing  task  not  privileged. 

lun    -   Integer  variable  specifying  the  logical  unit  number. 


18.5   ERROR  DETECTION  AND  RECOVERY 

Error  Detection  and   recovery  procedures  encompass   the   following 
contingencies. 

1.  Nonrecoverable  serial  line  errors 

2.  Power-fail  at  the  remote  station 
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3.  Power  recovery  at  the  processor 

4.  No  response  from  an  interrupting  module 

The  first  two  conditions  are  dealt  with  in  a  manner  similar  to  that  of 
other  types  of  unsolicited  interrupts.  Specifically,  such  occurrences 
may  cause  a  task  to  be  activated,  and  are  reported  to  all  tasks  that 
are  connected  to  digital,  counter,  or  terminal  input.  The  following 
paragraphs  discuss  specific  driver  activity  relating  to  each  error 
condition. 


18.5.1   Serial  Line  Errors 

The  driver  detects  nonrecoverable  serial  line  errors.  A 
nonrecoverable  error  condition  is  defined  as  the  occurrence  of  a 
predetermined  number  of  error  interrupts  in  an  interval  of  1  second, 
or  no  response  from  the  controller  upon  initiation  of  an  output  data 
transfer  by  means  of  the  serial  line.  The  occurrence  of  such  a 
condition  causes  the  driver  to  perform  as  follows: 

1.  Place  the  controller  in  a  "not  ready"  status. 

2.  Disable  further  error  interrupts. 

3.  Report  the  condition  to  the  task  that  is  linked  to  errors, 
and  to  any  tasks  connected  to  receive  unsolicited  interrupt 
data  from  the  faulty  unit.  Subsequent  QIO  requests  that 
transfer  data  to  or  from  the  unit  are  rejected  with  a  status 
of  lE.DNR. 

Requests  for  interrupting  modules  that  are  pending  (A/D  converters  and 
terminal  output)  are  allowed  to  time  out  with  the  error  code  lE.DNR. 
The  serial  line  error  rate  required  to  consider  the  link  inoperative 
may  be  specified  by  the  user  at  the  time  of  system  generation. 

After  reporting  the  error  as  described  above,  the  driver  wil.T 
automatically  remove  the  "not  ready"  status  when  the  error  condition 
is  not  detected  at  the  end  of  any  1-second  interval.  If  requested 
during  system  generation,  the  state  of  the  following  remote  modules 
will  be  restored  as  described. 

1.  Bistable  outputs  -  set  to  last  recorded  state 

2.  Counters  -  reinitialized  to  last  initial  value 

3.  Analog  outputs  -  restored  to  last  output  value 


18.5.2   Power-Fail  at  a  Remote  Site 

The  detection  of  AC-low  from  the  remote  site  will  immediately  trigger 
the  processing  described  in  Section  18.5.1.  The  absence  of  AC-low 
will  automatically  return  the  unit  to  the  "ready"  status. 
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If  specified,  the  state  of  the  following  remote  modules  will   then   be 
restored  as  described: 

1.  Bistable  outputs  -  set  to  last  recorded  state 

2.  Counters  -  reinitialized  to  last  initial  vali*e 

3.  Analog  outputs  -  restored  to  last  output  value 


18.  5.  :^  Power  Recovery  at  the  Processor 

Power  recovery  by  the  processor  will  initiate  the  activity  described 
in  Section  18.5.2  for  both  local  and  remote  file  boxes.  However, 
power  recovery  processing  at  the  processor  will  not  be  reported  to  a 
task  that  is  linked  to  error  interrupts  or  connected  to  receive 
unsolicited  interrupt  data. 


18.5.4   Unit  in  Off-line  Status 

A  unit  that  is  off  line  (see  Section  18.3.9.1)  is  considered  to  be 
under  manual  control  for  purposes  of  diagnosis  and  maintenance.  Under 
these  conditions,  error  reporting  as  described  in  Section  18.5.1  is 
unnecessary  and  frequently  undesirable,  since  fault  indications  are 
generally  a  by-product  of  these  activities  (that  is,  a  remote  unit  is 
shut  down  to  install  an  I/O  module),  not  the  result  of  a  genuine 
controller  fault. 

Furthermore,  to  permit  the  operation  of  diagnostic  software,  it  is 
advisable  to  attempt  to  service  all  QIO  requests  regardless  of  the 
controller  status.  Consequently,  under  these  circumstances,  error 
reporting  and  detection  are  modified  as  follows  when  the  controller  is 
off  line: 

'' ,  Access  to  the  controller  with  the  intention  of  transmitting 
data  to  or  from  the  device  is  restricted  to  privileged  tasks. 

2.  The  task  linked  to  error  interrupts  and  any  tasks  receiving 
interrupt  data  are  not  notified  of  remote  power-fail  or  fatal 
serial  line  errors. 

3.  All  device  error  interrupts  become  disabled. 

4.  An  attempt  is  made  to  service  all  QIO  requests  if  issued  by  a 
privileged  task.  If  such  requests  time  out  (that  is,  A/D 
converter  or  remote  terminal  output),  they  are  terminated 
with  the  error  code  IE. ABO  rather  than  with  lE.DNR.  No 
hardware  errors  are  reported  for  I/O  requests  that  are 
normally  completed  immediately  (for  example,  bistable  digital 
output) . 
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18.5.5   Error  Data  -  ICSR  and  ICAR  Registers 


Whenever  a  reportable  error  occurs,  the  driver  returns  the  contents  of 
the  appropriate  control  and  status  register  (ICSR)  and,  in  some  cases, 
the  contents  of  the  address  register  (ICAR),  to  assist  in  fault 
diagnosis.  Tables  lfl-8  and  18-9  describe  the  contents  of  these 
registers. 


Table  18-8 
ICSR  Contents 


Bit 

Name 

Read/ 
Write 

Description 

15 

OUTPUT  BUSY 

R 

Indicates   output   buffer   cannot 
accept  new  data. 

14 

MAINT 

R/W 

Maintenance. 

13 

NOT  USED 

R 

Always  set  to  1. 

12 

ERROR 

R 

Indicates       occurrence        of 
communication   serial   line  error. 
Reset  when  ICAR  is  read. 

11 

MAINT 

R/W 

Maintenance. 

10 

PWR  FAIL 

R 

Remote  Power  Supply  AC  LO  indicator. 

9 

TBMT  INT  EN 

R/W 

Enables  bit  15  of  ICAR  to  interrupt. 

8 

MAINT 

R/W 

Maintenance. 

7 

MOD  INT 

R 

Indicates    I/O   Module    requires 
interrupt  servicing. 

6 

RESET 

W 

Resets  all  I/O  modules.   Always  read 
as  0. 

5 

TTY  ENABLE 

R/W 

Activates   TTY   mode,   disables   I/O 
mode. 

4 

PWR  FAIL  INT 
ENABLE 

R/W 

Enables  bit  10  to  interrupt. 

3 

BMT  INT  ENABLE 

R/W 

Enables   complement   of   bit    15  to 
interrupt. 

2 

MOD  INT  ENABLE 

R/W 

Enables  Bit  7  to  interrupt. 

1 

ERROR  INT  ENABLE 

R/W 

Enables  Bit  12  to  interrupt. 

0 

RIF 

R/W 

Resets   the   interrupting    module's 
flag   when   set   and   the   module  is 
addressed.    This   clearing    action 
also  resets  the  RIF  bit. 
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Table  18-9 
ICAR  Contents 


Bit 

Name 

Description 

15 

TBMT 

Indicates   TTY  outp'jt  buffer   can 
accept  new  data. 

14 

PCL 

Pulse  closed.   This  bit  is  set  by  a 
jumper   on   a   digital   interrupt 
module.   This  jumper  is   removed   if 
contact  closures  are  not  of  interest 
to  the  user. 

13 

POP 

Pulse  Opened.   This  bit  is  set  by  a 
jumper   on   a   digital   interrupt 
module.   This  jumper  is   removed   if 
contacts  opening  are  not  of  interest 
to  the  user. 

12 

DA 

Indicates   terminal   character    has 
been   received.    Cleared  by  reading 
terminal  character. 

11-08 

Generic  Code 

A  4-bit  binary  code  that   identifies 
the   type   of   module  requesting  the 
interrupt . 

07-00 

Module  Address 

8-bit   address    of    the    module 
requesting  the  interrupt. 

# 


18.6   DIRECT  ACCESS 

Section  18.1.3  notes  those  ICS/ICRll  functions  that  may  be  performed 
by  referencing  a  module  through  its  physical  address  in  the  I/O 
page.  Under  rtSX-llM  such  access  is  accomplished  by  one  of  the 
following  methods: 

1.  A  privileged  task  or  any  task  running  in  an  unmapped  system 
has  unrestricted  access  to  the  I/O  page  and  may  therefore 
access  each  module  by  absolute  address. 

2.  Using  the  Task  Builder,  a  task  may  link  to  a  global  common 
area  whose  physical  address  limits  span  a  set  of  locations 
in  the  I/O  page.  This  method  applies  to  either  a  mapped  or 
unmapped  system. 

The  latter  method  allows  a  task  to  be  transported  to  any  other 
system  simply  by  relinking.  Moreover,  in  a  mapped  system  the  memory 
management  hardware  aborts  all  references  to  device  registers 
outside  the  physical  ad'^ress  limits  of  the  common  block. 

Because  the  software  allows  arbitrary  module  placement,  direct 
reference,  in  either  case,  must  be  accomplished  by  translating  a 
relative  module  numb  r  to  a  physical  or  virtual  register  address 
within  the  I/O  page.  This  translation  or  mapping  is  performed  by 
means  of  a  table  (ICTAB.MAC)  that  is  created  during  system 
generation,  and  inserted  in  the  system  object  module  library. 
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The  operations  required  to  implement  each  method  may  be   summarized 
as  followst 

1.   Unrestricted  access  to  the  I/O  page 

a.  Based  upon  the  user's  response  to  the  ICS/ICR  SYSGEN 
queries,  the  MACRO  source  file  ICTAB.MAC  is 
automatically  created  under  UIC  [11,10]  on  the  source 
disk.  This  file  contain?  tables  that  describe  the 
physical  location  of  each  counter,  digital  interrupt, 
and  digital  sense  module  in  the  target  system. 

b.  ICTAB.MAC  is  assembled  for  eventual  inclusion  in  the 
system  object  module  library. 

c.  The  MACRO  source  file  ICOM.MAC,  under  UIC  [11,10]  on 
the  source  disk,  is  assembled  to  generate  global 
definitions  for  the  first  ICS/ICR  address  on  the  I/O 
page  and  the  number  of  ICS/ICR  controllers  in  the 
target  system.  The  resulting  object  file  is 
incorporated  in  the  system  library  file. 

d.  A  task  is  built  containing  the  appropriate  global 
references.  Such  references  are  resolved  when  the  Task 
Builder  automatically  searches  the  system  library. 

Steps  a,  b,  and  c  are  executed  once.   Step  d   is   performed 
each  time  a  task  that  references  the  ICS/ICRll  is  created. 

NOTE 

ICS/ICR  inputs  are  not  valid  until  3ms  after  power 
recovery  at  the  processor.  Tasks  that  are 
referencing  inputs  directly  may  establish  a  power 
recovery  AST  entry  point  that  suspends  task 
execution  for  the  necessary  time  interval. 


2.   Access  to  the  I/O  page  through  a  Global  Common  Block: 

a.  Steps  a  and  b  are  performed. 

b.  File  ICOM.MAC  under  UIC  [11,10]  is  assembled  to  define 
the  first  ICS/ICR  module  address  as  a  relocatable 
vail  ,  the  number  of  I/O  page  locations  required,  and 
the  number  of  controllers  present  on  the  target  system. 

c.  File  ICOM.OBJ,  created  in  step  b.  Is  linked  using  the 
Task  Builder  to  create  an  image  of  the  device  common 
block  on  disk. 

d.  The  SET  and  INSTALL  MCR  or  VMR  commands  are  used  to 
allocate  spffce  for  the  common  block  and  declare  the 
block  resident  in  the  target  system. 

e.  A  task  is  created  containing  the  appropriate  global 
references  to  the  common  block  and  mapping  table. 
Common  block  references  are  resolved  by  directing  the 
Task  Builder  to  link  the  task  to  the  device  common 
block  (ICOM) .  The  mapping  table  reference  is  resolved 
from  the  system  library  module  ICTAB. 
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The  detailed  procedure  for  creating  the  necessary  object  files  and 
device  common  block  is  performed  automatically  as  part  of  the  system 
generation  process,  and  is  described  fully  in  the  RSX-llM  System 
Generation  and  Management  Guide.  Therefore,  the  discussion  in  the 
following  paragraphs  is  limited  to  procedures  for  linking  to  the 
device  common  block,  and  using  the  «:ile  ICTAB.MAC  to  determine 
module  addresses  within  the  I/O  page. 


18.6.1   Linking  a  Task  to  the  ICS/ICR  Common  Dlock 

Once  the  device  common  block  has  been  created,  a  task  may  access 
ICS/ICR  modules  by  linking  to  the  common  block.  This  can  be  done  by 
using  the  Task  Builder  commands  shown  in  the  following  3xample; 

TKB>TASK, LP: -TASK. OBJ 

TKB>/ 

ENTER  OPTIONS: 

TKB>    COMMON«ICOM:RO 

TKB>/ 

The  illustration  is  valid  for  either  a  mapped  or  unmapped  system. 
In  both  cases,  the  Task  Builder  links  the  task  to  the  common  block 
by  relocating  the  global  symbol  definitions  contained  in  the  common 
block  symbol  table  file  ICOM.STB  loca:ad  under  UIC  (1,1).  If  memory 
management  is  present,  the  Executive  will  map  the  appropriate 
physical  locations  into  the  task's  virtual  addressing  space  when  the 
task  is  male  active. 


18.6.2  Accessing  the  I/O  Page 

After  the  task  has  been  linked  to  the  I/O  page,  either  directly  or 
through  reference  to  the  device  common  block,  access  to  a  specific 
ICS/ICR  counter,  or  digital  input  modules  during  task  execution,  is 
a  3-step  process: 

1.  The  task  generates  a  request  for  module  data  by  specifying 
module  type,  relative  module  number,  and  physical  unit 
number. 

2.  The  data  contained  in  module  ICTAB  is  accessed  to  translate 
the  arguments  of  step  1  to  a  physical  offset  from  the 
ICS/ICR  base  address  on  the  I/O  page. 

3.  The  ICS/ICR  base  address,  defined  in  the  common  block  or 
system  library  module  that  was  created  from  file  ICOM.MAC, 
is  added  to  the  offset  to  compute  a  physical  or  virtual 
address  and  the  module  data  is  read. 

The  next  few  paragraphs  describe  the  format  of  the  system  library 
module  ICTAB,  and  common  block  module  ICOM  in  detail.  A  sample 
MACRO  subroutine  that  references  these  modules  is  then  presented. 


# 
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18.6.2. 
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INCREASING 

MEMORY 

ADDRESSES 


DIGITAL  SENSE 


DIGITAL  INTERRUPT 


COUNTER  MODULES 


DIGITAL  SENSE 


DIGITAL  INTERRUPT 


COUNTER  MODULES 


UNIT  0 
MAPPING  TABLE 


UNIT  N 
MAPPING  TABLE 


ZK0M-«1 


figure  18-1   Mapping  Table  Format 

The  structure  of  each  entry  is  depicted  in  Figure  lfl-2.  Entries  are 
18  bytes  long.  Byte  0  contains  the  highest  number  of  modules  of  a 
given  type  that  can  be  referenced  for  the  controller.  Bytes  2 
through  17,  when  indexed  by  relative  mc.dule  numbers,  yield  a  value 
between  0  and  255  representing  the  physical  location  of  the  module 
within  the  set  of  external  page  addresses  allocated  to  the 
ICS/ICRll. 

The  following  global  symbols  are  defined  by  this  module: 

. ICTAB  =  Location  of  mapping  tables 

I.CTBL  =  Length  in  bytes  of  one  set  of  entries 


.ICMD   =  First  ICS/ICR  virtual  or  physical  address 
I/O  page. 

I$$C11  =  Number  of  ICS/ICR  controllers 


within   the 


18-77 


INDUSTRIAL  CONTROL  SUBSYSTEMS 


If  the  global  common  block  was  built,  the  definitions  above  are 
contained  in  the  symbol  table  file  that  was  created  by  the  Task 
Builder;  otherwise,  they  are  '.ncluded  in  the  system  object  module 
library. 1 


BYTE 
0 
2 

4 
6 

e 

10 
12 
14 
16 


INCREASING 

MEMORY 

ADDRESS 


RESERVED 

MAX  MODULE  NO 

PHYSICAL  MODULE  NO 

PHYSICAL  MODULE  NO 

*                                     m 

- 

. 

■ 

• 

• 

• 

• 

" 

• 

• 

■ 

■ 

■ 

ZK-oio-ai 


Figure  18-2   Mapping  Table  Entry  Format 


18.6.2.3  Sample  Subroutine  -  The  following  subroutine,  residing  in 
the  system  library,  utilizes  the  modules  previously  described,  to 
read  ICS/ICR  module  data. 


;  READ  ICS/ICR-11  DIRECT  ACCESS  INPUTS 
;  LOCAL  DATA 

* 

;  ADDRESS  OF  ICS/ICR-11  MAPPING  TABLES 
. ENABL   LSB 


; 


N=0 
ICMAP: 


N=N+1 


.REPT 
.WORD 
.ENDR 


12. 
.ICTAB+I.CTBL*N> 


1  + 
I 


1.  TOe  definitions  are  included  in  module  ICOM  in  the  system  library 
or  in  the  STB  file  ICOM. STB  under  UIC[1,1)  on  the  system  disk.  The 
STB  file  is  automatically  referenced  by  the  Task  Builder  in  response 
to  the  use  of  the  LIBR  keyword. 
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t    **-.RDIC-READ  ICS/ICR-11  DIRECT  ACCESS  INPUTS 

THIS  SUBROUTINE  IS  CALLED  TO  TRANSLATE  RELATIVE  MODULE  NUMBER 
TO  PHYSICAL  EXTERNAL  PAGE  ADDRESS  AND  READ  THE  MODULE  DATA. 


INPUTS! 


RO 
Rl 


RELATIVE  MODULE  NUMBER 
MODULE  CODE 


WHERE: 


0  =  CONTACT  SENSE 

1  =  CONTACT  INTERRUPTS 

2  =  COUNTERS 


STACK  SETUP  IS  AS  FOLLOWS: 

(SP)+00  =  RETURN  TO  CALLER 

(SP)+02  =  I/O  STATUS  BLOCK  ADDRESS  (NOT 

REFERENCED) . 

;  (SP)+04    PHYSICAL  UNIT  NUMBER 

;  OUTPUTS: 


C/CLEAR 


C/SET: 


SPECIFIED 


RO 


MODULE  DATA 


NONEXISTENT  PHYSICAL  UNIT  NUMBER  OR  MODULE 


.RDIC: 


MOV 
CMP 
BLO 
ASL 


TO  WORD 


MOV 


4(SP) ,R2 

#I$$C11-1,R2 

10$ 

R2 


ICMAP(R2) ,R2 


ASL 

Rl 

ADD 

R1,R2 

« 

ASL 

Rl 

ASL 

Rl 

ASL 

Rl 

ADD 

R1,R2 

TSTB 

(R2) 

SEC 

BEQ 

10$ 

INCB 

RO 

CMPB 

(R2)+,R0 

BLO 

10$ 

INC 

R2 

ADD 

R0,R2 

CLR 

RO 

EXTEND 

BISB 

(R2) ,R0 

ASL 

RO 

MOV 

.iCMD(RO) ,R0 

10$: 

-   " 

RETURN 

GET  PHYSICAL  UNIT  NUMBER 

LEGAL  UNIT  NUMBER? 

IF  LO  NO 

CONVERT  PHYSICAL  UNIT  NUMBER 

OFFSET 

GET  ADDRESS  OF  MAPPING  TABLE 
ENTRIES  FOR  THIS  UNIT 
CONVERT  CODE  TO  WORD  OFFSET 
MULTIPLY  OFFSET  BY  9  AND  ADD 
TO  TABLE  ADDRESS 


COMPUTE  OFFSET  TO  TABLE 

MODULE  EXIST? 

ASSUME  NO 

IF  EQ  NO 

CONVERT  TO  NUMBER  OF  MODULES 

LEGAL  MODULE  NUMBER? 

IF  LO  NO 

POINT  TO  TABLE  ENTRIES 

OFFSET  TO  MODULE  NUMBER 

SET  FOR  MOVB  WITHOUT  SIGN 

GET  INDEX  TO  MODULE 
CONVERT  TO  WORD  OFFSET 
GET  MODULE  DATA 


END 
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18.7   CONVERSION  OF  EXISTING  SOFTWARE 

The  following  paragraphs  are  intended  as  guidance  in  converting 
existing  UDC  or  ICS  software  to  run  under  the  ICS/ICR-11  driver  and 
associated  FORTRAN  support  routines.  The  differences  described  here 
are  restricted  to  module  support  and  features  that  would  affect 
existing  software.  New  features,  unsupported  in  previous  systems, 
are  not  discussed. 


IB. 7.1  Features 

Principal  features  affecting  existing  software  are: 

1.  Support  for  the  ICS/ICRll  as  a   multiunit,  multicontroller 
device 

2.  Removal   of   software   restrictions  on   the   placement  of 
functionally  similar  modules 

Multiunit  support  affects  any  software  that  addresses  modules 
outside  the  range  of  a  single  file  box.  In  general,  such  software 
must  be  modified  at  the  source  level. 

Unrestricted  module  placement  affects  MACRO-11  programs  that 
directly  access  digital  input  and  counter  modules.  Such  programs 
may  utilize  the  library  routine  described  in  Section  18.3  to  read 
data  from  these  modules. 


18.7.2  Module  Support 

18.7.2.1   lAD-IA  A/D  Converter  and  IMX-IA  Multiplexer 
MACRO  Interface: 

Identical  to  UDCll  driver 

FORTRAN  Interface: 
Same  as  UDCll 

Functional  Differences: 

The  ICS/ICR  driver  can  initiate  parallel  conversions  on  each 
lAD-IA  in  a  file  box  that  is  referenced  by  a  single  QIO 
request.   The  UDCll  driver  performs  all  conversions  serially. 

The  ICS/ICR  driver  supports  any  permissible  configuration  of 
lAD-IA  A/D  converters  and  IMX-IA  multiplexers.  The  UDCll 
driver  requires  that  eight  module  slots  be  reserved  for  each 
lAD-IA  ii  the  system  regardless  of  the  actual  number  of 
multiplexe  ^  installed. 
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18.7.2.2   16-Bit  Binary  Counter 

MACRO  Interface: 

Identical  to  UDCll  driver 

FORTRAN  Interface:  '  , 

Same  as  UDCll;  however,  if  the  counter  is  read  through  a  call 
to  RDTI,  then  the  task  must  be  relinked  to  incorporate  the 
revised  FORTRAN  Interface  routine. 

Functional  Differences: 

The  ICS/ICR  driver  permits  any  task  to  reset  an  initial  counter 
value  (with  FORTRAN  call  SCTI  or  through  the  10. ITI  QIO 
function) .  The  UDCll  driver  restricts  this  operation  to  a  task 
that  has  connected  to  counter  interrupts. 


18.7.2.3  Bistable  Digital  Output 
MACRO  Interface: 

Identical  to  UDCll 

FORTRAN  Interface: 

Identical  to  UDCll 

Functional  Differences: 
None 

18.7.2.4  Momentary  Digital  Output 
MACRO  Interface: 

User  interface  is  achieved  with  the  QIO  lO.MSO  issued  to  the 
ICS/ICR-i:  driver.  The  UDCll  driver  does  not  support  this 
function  since  the  module  may  be  accessed  directly  through  the 
UDC  device  common  block. 

FORTRAN  Interface: 

Identical  to  UDCll;  however,  existing  FORTRAN  tasks  must  be 
relinked  to  i.. elude  ICS/ICRll  FORTRAN  interface  routines. 

Functional  Differences: 

- ';   Momentary  output  operations  are  now  processed   by  the   ICS/ICR 
driver,  rather  than  through  direct  access  to  the  I/O  page. 
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18.7.2.5  Nonint«rruptlng  Digital  Input 

MACRO  Interface: 

MACRO  Interface  is  by  moans  of   the   ICS/ICRll   device  common 
block  and  mapping  table  described  in  Section  18.6. 

FORTRAN  Interface: 

Identical  to  UDCll;   however,  existing  tasks  must   be   relinked 
to  include  revised  ICS/ICRll  FORTRAN  interface  routines. 

Functional  Differences: 
None 


18.7.2.fi  Analog  Output 

MACRO  Interface: 

User  interface  is  achieved  w< th  the  QIO  10. SAO   issued   to  the 

ICS/ICR  driver.    The   UDCl.   driver   does   not   support  this 

function  since  the  module  may  be  accessed  directly  through  the 
UDC  device  common  block. 


FORTRAN  Interface: 

Identical  to  UDCll;   however,  existing  FORTRAN   tasks  must  be 
relinked  to  include  ICS/ICRll  FORTRAN  interface  subroutines. 

Functional  Differences: 

Analog  output  operations   are   now  processed  b)      the   ICS/ICR 
driver  rather  than  through  direct  access  to  the  I/O  page. 


18.7.2.7   Interrupting  Digital  Input 
MACRO  Interface: 

Identical  to  UDCll  driver 

FORTRAN  Interface: 

Identical  to  UDCll  driver;  however,  if  digital  inputs  are  read 
through  the  call  to  RCIPT,  then  the  task  must  be  relinked  to 
incorporate  the  revised  ICS/ICRll  FORTRAN  interface  routines. 

Functional  Differences: 
None 


m 
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CHAPTER  19 
MULL  DEi^ICE  DRIVER 


RSX-llM  provides  a  driver  for  a  software  construct  called  the  "null 
device.*  The  mnemonic  for  the  null  device  is  NL:,  and  its 
characteristics  are  as  follows: 

•  A  read  from  NL:   returns  an  end-of-file  error  (IE. EOF). 

e  A  write  to  NL:   immediately  returns  f^uccess  (IS.SUC)  . 

The  null  device  functions  as  a  "black  ho(tt"  to  which  you  can  direct 
output,  and  from  which  it  will  never  return.  It  is  particularly 
us  iful  when  used  in  conjvs  iJtion  with  an  indirect  command  file  and  NCR 
ASN  commands,  as  in  the  example  below. 

Figure  19-1  shows  the  contents  of  a  Tdsk  Builder  command  file  called 
TESTBLD.CMD.  Symbolic  device  names  are  usr>d  for  the  out^^ut  file,  map 
file,  and  input  file.  These  names  may  be  rea&s>igned  at  task-build 
time.  In  particular,  in  the  example  beiow,  the  map  file  is  assigned 
to  the  null  device  and  thus  is  thrown  away. 

>ASN  SY:-OU: 

>ASN  NL:<-MP: 

>ASN  DK1;-IN: 

>TKB  ^TESTBLD 


OU: 

TEST, MP 

TEST* 

'IN: 

[200, 

2201TEST 

/ 

ASG 

-TI:2 

// 

Figure  19-1   Indirect  TKB  Command  File  TESTBLD.CMD. 
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CHAPTER  20 
GRAPHICS  DISPLAY  DRIVER 


20.1   INTRODUCTION 

RSX-llM  provides  support  for  two  graphics  display  peripherals:  the 
VTll  and  the  VS60.  Graphics  display  drivers  are  not  supported  in 
RSX-llM-PLUS  systems.  Each  consists  of  a  CRT  display,  light  pen,  and 
display  processing  unit  (DPU) .  Either  may  be  purchased  separately  or 
as  part  of  a  complete  system.  For  example,  the  GT46  is  a  "starter 
system"  consisting  of  a  VTll  and  a  PDP-llT/34  with  32K  words  of  memory 
and  disk  storage. 


20.1.1  VTll  Graphics  Display  Subsystem 

The  VTll  is  a  low-cost,  line-drawing  graphics  display  subsystem.  It 
steals  cycles  asynchronously  from  the  CPU  whose  UNIBUS  it  shares.  Its 
DPU  instruction  set  supports  the  following  features: 

Relative  and  absolute  vectors  —  solid,  long  dash,  short  dash, 
or  dotted 

Point  plotting 

Character  generation 

Blinking  display 

Eight  levels  of  intensity 

Light-pen  interaction 


20.1.2  VS60  Graphics  Display  Subsystem 

The  V560  supports  all  these  features  at  a  higher  rate  of  performance 
than  the  VTll.  In  addition,  the  VSfiO  supports  hardware  subroutining , 
scaling,  and  windowing.   A  second  CRT  may  be  added  to  the  VS60. 


20.2   GET  LUN  INFORMATION  MACRO 

Word  2  of  the  buffer  filled  by  the  GET  LUN  INFORMATION  system 
directive  (the  first  characteristics  word)  contains  Os  in  all  bits  for 
graphics  display  devices.   Words  3,  4,  and  5  are  undefined. 
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20.3  QIO  MACRO 

Table  20-1  lista  the  standard  and  device-specific  functions  of  the  QIO 
macro  that  are  valid  for  graphics  display  devices. 

The  standard  QIO  functions  10. ATT  and  lO.DET  have  little  use  in  the 
graphics  display  driver,  because  the  specific  functions  10. CON  and 
lO.DIS  are  available. 


Table  20-1 
Standard  and  Device-Specific  QIO  Functions  for  Graphics  Displays 


Format 

Function 

STANDARD  FUNCTIONS 

Attach  device 
Detach  device 
Cancel  I/O  requests 

CONNECT  to  graphics 
device  (start  DPU) 

Continue  (restart  DPU) 

Disconnect  from  graphics 
device  (halt  DPU) 

Stop  (halt  DPU) 

QIOSC  10. ATT,... 
QIO$C  lO.DET,... 
QIOSC  lO.KIL,... 

DEVICE-SPECIFIC  FUNCTIONS 

QIOSC  IO.CON,...,<stadd,size 

t,lpef] [,lpast]> 

QIOSC  lO.CNT,... 

QIOSC  lO.DIS,... 

QIOSC  lO.STP,... 

stadd 


The  starting  address  of  a  display  file  (must  be  word  aligned) . 
The  display  file  must  be  within  the  lowest  28K  of  physical  memory 
for  the  VTll. 


all* 


The  size  of  the  display  buffer  in  bytes. 


Ipaf 


The  optional  number  of  an  event  flag  to  be  set  upon  light-pen 
hit;   in  the  range  1-64  (10). 


Ipast 


The  optional  address  of  an  asynchronous  system  trap   (AST)   entry 
point  to  be  used  upon  light-pen  hit. 
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20.4   STATUS  RETURNS 

Table  20-2  lists  error  and  status  conditions  that  are  returned  by  the 
graphics  display  driver  in  the  first  word  of  the  I/O  status  block. 
The  second  I/O  status  word  always  contains  0. 


Table  20-2 
Graphics  Display  Status  Returns 


Code 

Reason 

IS. sue 

Successful  completion 

The  operation   specified   in   the   QIO  directive   was 

( 

completed  successfully. 

IE. ABO 

Operation  aborted 

The  I/O  operation  was  cancelled   by   lO.KIL  while   in 

progress  or  in  the  I/O  queue. 

IE. CNR 

Connection  rejected 

The  graphics  device  specified  in  an  10. CON  function  was 

already  connected  to  another  task. 

lE.DNA 

Device  not  attached 

The  graphics  device  specified  in  an  lO.DET  function  was 

not  attached  to  the  issuing  task. 

lE.IEF 

Illegal  event  flag 

An  event  flag  number  specified   in  an   10. CON   function 

(Ipef  argument)  was  not  in  the  range  1-64  (decimal). 

lE.IFC 

Illegal  function  code 

A  function  code  was  specified  in  an  I/O  request  that   is 

illegal  for  graphics  display  devices. 

lE.SPC 

Illegal  address  space 

The  display  buffer   specified   in  an   10. CON   function 

(stadd   argument)   was   not   word   aligned,  or  (for  VTll 

only)  was  not  completely  within   the   lowest   28K  of 

memory. 

20.5   PROGRAMMING  HINTS 

The  graphics  display  driver  does  not  determine  what  appears  on  the 
screen  of  the  VTll  or  YS60.  The  key  to  what  is  drawn  is  the 
collection  of  DPU  instructions  in  the  display  buffer. 
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Under  normal  circumstances,  the  display  buffer  ts  generated  by  calls 
to  a  set  of  FORTRAN  graphics  subroutines.  These  subroutines  provide  a 
more  convenient  access  to  the  graphics  features  of  the  hardware  than 
il^  u/"!:'  ^^^      instructions.   The  subroutines  are  described  in  thd 

DECqraphlc-11  FORTRAN  Reference  Manual,  order  number  DEC-11-GFRMA-A-D. 

Aborting  a  VTl 1  task  may  cause  an  RSX-llM  system  to  hang  up 
indefinitely,  requiring  a  bootstrap.  The  VTll  DPU  has  no  Halt 
instruction,  but  the  I/O  driver  must  halt  the  DPU  before  it  can  return 
a  success  status  in  response  to  an  lO.KIL  request.  (lO.KIL  is 
automatically  generated  when  a  task  is  aborted.)  This  hang  situation 
cannot  arise  with  a  VS60. 
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CHAPTER  21 
LABORATORY  PERIPHERAL  ACCELERATOR  DRIVER 


21.1   INTRODUCTION 


The  Laboratory  Peripheral  Accelerator  (LPAll-K)  is  an  intelligent, 
direct  memory  access  (DMA)  controller  for  DIGITAL'S  laboratory  data 
acquisition  I/O  devices.  It  is  a  fast,  flexible,  and  easy-to-use 
microprocessor  subsystem  that  allows  analog  data  acquisition  rates  up 
to  150,000  samples  per  second.  The  LPAll-K  is  designed  for 
applications  requiring  concurrent  data  acquisition  and  data  reduction 
at  high  rates. 

The  LPAll-K  is  supported  through  a  device  d  ver  and  a  set  of 
program-callable  routines.  The  device  driver  supports  multiple 
controllers  and  can  be  configured  as  resident  or  loadable.  The 
program-callable  support  routines  are  linked  with  the  user's  task  at 
task-build  time.  These  routin:JS  are  highly  modular.  Therefore,  a 
particular  task  contains  only  that  code  necessary  for  the  facilities 
actually  used. 


The   LPAll-K 
multi  request . 


op     s   in   two   distinct    modes:     dedicated 
T     .bsections  that  follow  summarize  each  mode. 


and 


21.1.1   LPAil-K  Dedicated  Mode  of  Operation 


In  dedicated  mode,  only  one  user  (that  is,  one  request)  can 
at  a  time  and  only  analog  I/O  data  transfers  are  supported, 
analog  converters   can   be   controlled   simultaneously.    Sc 

<_.->..■  -I 1    1 £^ _c  i.u_ 1   I.; _T I. 1 


a 
a 

Initiated   by   an 
supplied  signal 


be   active 

Up  to  two 

»-cni   kjc   v^v^iiuL^^j.j.c=^j   ojLiiiu.L(-ciiicjv^uoiy.    Sampling   is 

overflow  of  the  real-time  clock  or  by  an  externally 


21.1.2   LPAll-K  Multirequest  Mode  of  Operation 

In  multirequest  mode,  sampling  from  all  device  types  is  supported.  Up 
to  eight  users  can  be  simultaneously  active.  The  sampling  rate  for 
each  user  is  a  multiple  of  the  common  real-time  clock  rate. 
Independent  rates  can  be  maintained  for  each  user.  Both  the  sampling 
rate  and  the  device  type  are  specified  as  part  of  each  data  transfer 
request. 
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2]. 2   GET  LUN  INFORMATION  MACRO 

If  a  Get  LUN  Information  syittem  directive  is  issued  for  a  LUN 
associated  with  an  LPAll-K,  word  2  (the  first  characteristics  word) 
contains  all  zeros,  words  1  and  4  are  undefined,  and  word  5  contains  a 
l*>-bit  buffer  preset  value  that  controls  the  rate  of  the  real-time 
clock  interrupts. 


21.")   THE  PROGRAM  INTERFACE 

A  collection  of  program-callable  subroutines  provides  access  to  the 
LPAll-K.  The  formats  of  these  calls  are  fully  documented  here  for 
FORTRAN  programs.  MACRO-11  programmers  access  these  same  subroutines 
either  through  the  standard  subroutine  linkage  or  through  the  usi  of 
two  special-purpose  macros.  Optionally,  MACRO-11  users  can  control  an 
LPAll-K  directly  through  the  use  of  device-specific  QIO  functions. 
Both  FORTRAN  and  MACRO  programs  must  contain  at  least  one  I/O  Status 
Block  (lOSB)  for  retrieval  of  status  information.  The  following 
subsections,  therefore,  describe: 

•  The  FORTRAN  interface 

•  The  MACRO-11  interface 

•  The  I/O  status  block 

NOTE 

The  subroutines  documented  in  this 
chapter  represent  the  high-level 
interface  to  the  LPAll-K.  Using  these 
subroutines  requires  an  understanding  of 
hardware  capabilities,  configuration 
details,  and  hardware  status  codes  as 
described  in  the  LPAll-K  Laboratory 
Peripheral  Accelerator  User ' s  Guide. 


21.3.1   FORTRAN  Interface 

Table  21-1  lists  the  FORTRAN  Interface  subroutines  for  accessing  the 
LPAll-K. 

The  calling  sequences  of  the  routines  listed  in  Table  21-1  are 
compatible  with  the  K-series  support  routines,  described  in  Chapter 
22,  except  as  noted.  The  following  subsections  briefly  describe  the 
function  and  fori^at  of  each  FORTRAN  subroutine  call. 
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Table  21-1 
FORTRAN  Subroutines  for  the  LPAll-K 


Subroutine 

Function 

ADSWP 

Initiate  synchronous  A/D  sweep 

CLOCK A 

Set  Clock  A  rate 

C.'.OCKB 

Control  Clock  B 

CVADF 

Convert  A/D  input  to  floating  point 

DASWP 

Initiate  synchronous  D/A  sweep 

DISWP 

Initiate  synchronous  digital  inp^t 

sweep 

DOSWP 

Initiate  synchronous  digital  output 

sweep 

PLTlfi 

Convert  unsigned  integer  to  a  real 

constant 

IBFSTS 

Get  buffer  status 

IGTBUF 

Return  buffer  number 

INXTBF 

Set  next  buffer 

IWTBUF 

Wait  for  buffer 

LAMSKS 

:»et  masks  bufler 

RLSBUP 

Release  dvta  buffer 

RMVBUF 

Remove  buffer  from  device  queue 

SETADC 

Set  channel  information 

SETIBF 

Set  array  for  buffered  sweep 

STPSWP 

Stop  sweep 

XRATE 

Compute  clock  rate  and  preset 

21.3.1.1  ADSWP:  Initiate  Synchronous  A/D  Sweep  -  The  ADSWP  routine 
initiates  a  synchronous  A/D  input  sweep  through  an  LPS-11  or  an  ADll-K 
(and,  if  present,  the  AMll-K) . 

If  differential  input  is  desired  for  the  ADl 1-K/AMll-K,  the  channel 
increment  must  be  set  to  2  by  calling  the  SETADC  routine.  The  default 
channel  increment  is  1  (single-ended  input) . 
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The  ADSWP  call  is  as  follows; 

CALL  ADSWP  (ibuf ,lbuf ,rnbuf1 , fmodel , ridwell] , riefnK fldelayl , 
fichn] , [nchn] , find] ) 


■ibu 


ibuf 


A  40-word  array  Initialized  by  the  SETIBP  routine.   The  first  two 
words  of  the  array  are  the  T/0  status  block  (lOSB). 


Ibuf 


mode 


The  size  in  words  of  each  data  buffer.  All  data  buffers  must  be 
equal  in  size  and  Ibuf  must  be  greater  than  5.  In  dedicated 
mode,  Ibuf  must  be  at  least  257  words. 


The  number  of  buffers  to  be  filled.  If  nbuf  is  omitted  or  set 
equal  to  0,  indefinite  sampling  occurs.  The  STPSWP  routine 
terminates  indefinite  sampling. 


The  sampling  options.  The  default  is  0.  The  mode  bit  values 
listed  below  that  are  preceded  by  a  plus  sign  {*)  are  independent 
and  can  be  added  or  ORed  together  (assuming  that  the  sampling 
options  are  applicable  to  the  mode  of  operation).  Those  values 
not  preceded  by  a  plus  sign  are  mutually  exclusive  and  only  one 
such  value  can  be  used  at  a  time.  All  bit  values  not  listed 
below  are  reserved. 

The  following  values  can  be  specified: 

0  Absolute  channel  addressing  (default).  This  mode 
allows  the  user  to  directly  access  all  fi4  channels  of 
an  A/D  converter. 

+32  Dual  A/D  conversion  serial/parallel.  This  option 
applies  to  dedicated  mode  only.  It  is  ignored  in 
multirequest  mode. 

+64  Multirequest  mode.  If  this  value  is  not  specified,  the 
request  is  for  dedicated  mode.  If  the  request  mode 
does  not  match  the  mode  of  the  hardware  (that  is, 
different  microcode  in  the  master  microprocessor),  the 
LPAll-K  rejects  the  request  with  an  appropriate  error 
code. 

+512  External  trigger  (STl).  This  mode  is  used  when  a 
user-supplied  external  sweep  trigger  is  desired.  The 
external  trigger  is  supplied  by  a  jumper  connecting  the 
ADll-K  External  Start  input  to  the  KWll-K  Schmitt 
Trigger  1  output.   This  external  trigger  connection  can 

—  -r  only  be  used  in  Dedicated  Mode.  If  mode  512  is 
selected,  the  user  task  must  specify  a  Clock  A  rate  of 

-1   for   proper  A/D  sampling.   This  is  non-clock-driven 

sampling. 
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+1024   Time  stamp  with  Clock  B  (Mult i request  mode  only). 

-t-2048  Event  marking  (Multi  request  mode  only).  LAMSKS  must  be 
called  to  specify  an  event  mark  channel  and  event  mark 
mask. 

+4096  Start  method.  If  set,  digital  input  start.  If  clear, 
immediate  start.  LAMSKS  must  be  called  to  specify  a 
digital  start  channel  and  digital  start  mask 
(multirequest  mode  only) . 

+8192  Dual  A/D  converter  (dedicated  mode  only). 

+lfi384  Data  overrun  NON-FATAL/FATAL.  If  selected,  data 
overrun  is  considered  nonfatal.  The  LPAll-K 
automatically  defaults  to  fill  buffer  0.  (See  Section 
21.4  for  a  discussion  of  buffer  management.) 


idwell 


The  number  of  clock  overflows  (pulses)  between  data  sample 
sequences.  As  an  example,  if  idwell  is  20  and  nchn  is  3,  the 
following  occurs:  after  20  pulses,  one  channel  is  sampled  on 
each  of  the  next  three  pulses.  Then,  no  sampling  takes  place  for 
the  next  20  pulses.  In  multirequest  mode,  this  facility  permits 
different  sample  rates  for  the  same  hardware  clock  rate  and 
preset.  In  dedicated  mode,  the  clock  hardware  rate  controls 
sampling  and  this  idwell  argument  is  ignored. 

If  compatibility  with  K-series  support  routines  is  desired,  the 

user   task  must   first  establish  the  clock  preset  by  calling  the 

CLOCKA  routine.   The  default  idwell  value  of  1   is   used   in  the 

sweep  start  command.  For  the  K-series,  this  procedure  sets  the 
rate  as  desired. 


NOTE 

This  parameter  is  called  iprset  in  the  K-series  support 
routines  described  in  Chapter  22.  Its  function  is 
different  from  the  idwell  parameter  described  here. 


iefn 


The  event  flag  (1  to  28,  30  to  96),  the  name  of  a  completion 
routine,  or  0.  If  0  or  defaulted,  event  flag  30  will  be  used  for 
internal  synchronization.  If  iefn  is  an  event  flag,  the  selected 
event  flag  is  set  as  each  buffer  is  filled.  Note  that  event  flag 
29  is  reserved  for  use  by  the  LPAll-K  support  routines  for 
internal  synchronization.  If  iefn  is  greater  than  96,  it  is 
considered  to  be  a  completion  routine  that  will  be  called  with  a 
JSP  PC.  Such  routines  must  return  with  an  RTS  PC  (or  a  FORTRAN 
RETURN  statement)  . 
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FORTRAN  completion  routines  must  not  contain  any  of  the 
following : 

•  Any  I/O  through  the  FORTRAN  run-time  system 

•  Any  use  of  virtual  arrays 

•  Any  use  of  floating-point  operations 

•  Any  errors,  since  error  reporting  is  done  through  the   FORTRAN 
run-time  system 

•  Anything  else  that  may  change  the  FORTRAN  impure  area 

Any  of  the  above  may  result  in  fatal  task  errors  or  unpredictable 
results. 

If  multiple  sweeps  are  initiated,  the  user  should  specify 
different  event  flags.  Adherence  to  this  limitation  cannot  be 
enforced  by  the  software. 


Idelay 


The  delay  from  the  start  event  (DRll-K)  until  the  first  sample  in 
IRATE  units.  This  feature  is  supported  in  multirequest  mode 
only.   Default  or  0  indicates  no  delay. 


ichn 


The  number  of  the  first  channel  to  be  sampled.  The  default  of  0 
applies  only  if  ichn  was  not  established  in  a  prior  call  to  the 
SETADC  routine. 


nchn 


ind 


The  number  of  channels  to  sample.  The  default  is  1.  nchn  may  be 
set  up  with  the  SETADC  routine.  The  number  of  channels  specified 
are  sampled  at  a  rate  of  1  per  clock  interrupt.  If  nchn  equals 
1,  the  single  channel  bit  is  set  in  the  mode  word  of  the  start 
RDA. 


Receives  a  success  or  failure  code  as  follows: 

1   indicates  that  the  sweep  was  successfully  initia?ized. 

0   indicates  an  illegal   argument   list,   or   SETIBF  was  not 
called  prior  to  this  call. 

-1  indicates  a  QIO  directive   failure.    The  directive   error 
code  is  placed  in  lOSB(l)  in  IBUF. 


NOTE 

The  ind  parameter  is  not  supported  by  the  K-series 
support  routines.  If  compatibility  with  K-series 
support  routines  is  desired,  this  p<<,rameter  must  be 
ignor>3d. 
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21.3.1.2  CLOCKA:  Set  Clock  A  Rate  -  The  CLOCKA  routine  sets  the   rate 
for  Clock  A.   This  routine  is  called  as  follows: 

CALL  CLOCKA  ( i rate , iprset , [ ind] , ( lun] ) 

ir«te 

The  clock  rate.   One  of  the  following  must  be  specified: 

-1  Direct-coupled  Schmitt  Trigger  1  (used  only  for  A/D  sweeps 
in  Dedicated  Mode  •t-512;  not  supported  by  K-series  support 
routines) 

0  Clock  B  overflow  or  no  rate 

1  1  MHz 

2  100  KHz 

3  10  KHz 

4  1  KHz 

5  100  Hz 

6  Schmitt  Trigger  1 

7  Line  frequency 


iprset 


vW 


Iw 


The  two's  complement  value  for  clock  preset.  The  clock  rate 
divided  by  the  negative  clock  preset  value  yields  the  clock 
overflow  rate.  For  example,  to  obtain  a  clock  overflow  rate  of 
10  Khz  with  a  clock  rate  of  IMhz,  iprset  *  -100  (minus  100 
decimal).  The  XRATE  routine  can  be  used  to  calculate  a  clock 
preset  value. 


Receives  a  success  or  failure  code  as  follows: 

0  indicates  an  illegal  argument  list  or  I/O  error.  Possible 
causes  are:  microcode  not  loaded;  driver  not  loaded; 
device  off  line  or  not  in  system. 

1  indicates  Clock  A  set  to  start  when  sweep  requested. 


The  logical  unit  number.   The  default  is  7, 


21.3.1.3  CLOCKB:  Control  Clock  B  -  The  CLOCKB  routine  gives  the   user 
control  over  the  KWll-K  Clock  3. 

The  CLOCKB  call  is  as  follows: 

CALL  CLOCKB  ([ i rate] , iprset , mode , f ind] ,[ lun] ) 
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irat* 


The  clock  rate.  When  irate  Is  nonzero,  the  clock  Is  set  running 
a*-  the  selected  rate  after  the  preset  value  specified  by  iprset 
is  loaded.  A  0  irate  stops  the  clock.  When  Irate  is  0  or 
default,  the  iprset  and  mode  parameters  are  ignored. 

The  following  values  are  acceptable  for  irate: 


0 

Stop  clock  B 

I 

IMHz 

2 

100  KHz 

3 

10  KHz 

4 

1  KHz 

5 

100  Hz 

e, 

Schmitt  Trigger  1 

7 

Line  frequency 

iprset 

The  count  by  which  to  divide  clock  rate  to  yield  overflow  rate. 
Overflow  events  can  be  used  to  drive  clock  A.  The  preset 
parameter  must  be  specified  as  0  or  as  a  negative  number  in  the 
range  -1  to  -2S5.  The  value  in  iprset  can  be  established  by  use 
of  the  XRATE  routine. 

mode 

The  options.  The  mode  bit  values  listed  belov  that  are  preceded 
by  a  plus  sign  (■♦■)  are  independent  and  can  be  added  or  ORed 
together.  Those  values  not  preceded  by  a  plus  sign  are  mutually 
exclusive  and  only  one  such  value  can  be  used  at  a  time.  All  bit 
values  not  listed  below  are  reserved. 

1  indicates  Clock  B  operates  in  noninterrupt  mode.  The 
Ifi-bit  clock  is  not  incremented  or  altered.  This  allows  a 
greater  than  lOKHz  pulse  to  be  sent  to  Clock  A. 

+7  indicates  the  feed  B  to  A  bit  will  be  set  in  the  Clock  B 
status  register. 


ind 


Receives  a  success  or  failure  code  as  follows: 

0  indicates  an  illegal  argument  list  or  I/O  error.  Possible 
causes  are:  microcode  not  loaded;  driver  not  loaded; 
device  off  line  or  not  in  system. 

1  indicates  Clock  B  started. 


lun 


The  logical  unit  number  (LUN).   The  default  LUN  is  7. 


^ 
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21.3.1.4  CVADP:  Convert  A/D  Input  to  Floating  Point  -  The  CVADF 
routine  converts  an  A/D  input  value  to  a  floating-point  number.  The 
routine  can  be  invoked  as  a  subroutine  or  a  function  as  follows: 

CALL  CVADF  (ival,val) 


or 


ival 


v«l 


val  -  CVADP(ival) 


A  value  obtained  from  A/D  input.   Bits  1?-1S  are   0.    Bits   n-11 
represent  the  value. 


(REAL*4)  receives  the  converted  value.   The  converted   value   is 
calculated  with  the  following  formula: 

val  *  (fi4*ival ) /gain 


21.3.1.S  DASWP:  Initiate  Synchronous  D/A  Sweep  -  The   DASWP   routine 
initiates  synchronous  D/A  output  to  an  AA17-K. 

The  DAf;wp  call  is  as  follows: 

CALL  DASWP  (ibuf ,lbuf ,rnbuf] , rmode] , ridwell] , [iefn] .Idelay, 
richnl , rnchn] , find]  ) 


ibuf 


A  4n-word  array  initialized  by  the  SETIBF  routine.   The  first  two 
words  of  the  array  are  the  I/O  status  block  (lOSB) . 


Ibuf 


The  size  in  words  of  each  data  buffer.  All  data  buffers  must  be 
equal  in  size  and  Ibuf  must  be  greater  than  S.  In  dedicated 
mode,  Ibuf  must  be  at  least  ?57  words. 


nbuf 


mode 


The  number  of  buffers  to  be  emptied.  If  nbuf  is  omitted  or  set 
equal  to  0,  indefinite  sweeping  occurs.  The  STPSWP  routine 
terminates  indefinite  sweeping. 


The  start  criteria.  Except  where  noted,  the  plus  sign  (+) 
preceding  mode  bit  values  listed  below  indicates  that  they  are 
Independent  and  can  be  added  or  ORed  together.  All  bit  values 
not  listed  below  are  reserved. 


^BET 
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The  lollowing  values  can  be  specified; 

0      indicates  immodiate  start.   This  is  the  default. 

♦114  lul  ti  request  mode.  If  ^.hls  value  is  not  specified,  the 
request  is  for  dedicated  mode.  If  the  request  mode 
does  not  match  the  mode  of  the  hardware  (that  is, 
different  microcode  in  master  microprocessor),  the 
LPAll-K  rejects  the  request  with  an  appropriate  error 
code. 

♦409fi  Start  method.  If  set,  digital  input  start.  I!  clear, 
immediate  start.  LAMSKS  must  be  called  to  specify  a 
digital  start  channel  and  a  digital  start  mask 
(mul tirequest  mode  only). 

♦16384  Data  overrun  NON-FATAL/FATAL.  If  selected,  data 
overrun  is  considered  nonfatal.  The  LPAll-K 
automatically  empties  buffer  0.  (See  Section  21.4  for 
a  discussion  of  buffer  management.) 


idwell 


The  number  of  clock  overflows  (pulses)  between  data  sample 
sequences.  For  example,  if  idwell  is  20  and  nchn  is  3,  the 
following  occurs:  After  20  pulses,  one  channel  is  emptied  on 
each  of  the  next  three  pulses.  Then,  no  emptying  takes  place  for 
the  next  20  pulses.  In  r>ul  ti  request  mode,  this  facility  permits 
different  rates  for  the  same  hardware  clock  rate  and  preset.  In 
dedicated  mode,  the  clock  hardware  rate  controls  .sampling  and 
idwell  in  the  sweep  start  command  is  ignored. 

If  compatibility  with  K-series  support  routines  is  desired,  the 
user  task  must  first  establish  the  clock  prtset  by  calling  the 
CLOCKA  routine.  The  default  value  (1)  for  the  idwell  parameter 
in  the  sweep  start  command  must  Li  used.  For  the  K-series,  this 
procedure  sets  the  rate  as  desired.  For  the  LPAll-K,  this 
procedure  results  in  idwell  in  the  sweep  call  defaulting  to  1, 
thus  yielding  the  same  clock  rate. 


NOTE 

This  parameter  is  called  iprset  in  the  K-series  support 
routines  described  in  Chapter  22.  Its  function  is 
different  from  the  idwell  parameter  described  here. 


i«fn 


An  event  flag  number  (1  to  28,  30  to  9fi) ,  or  the  name  of  a 
completion  routine,  or  0.  If  0  or  default,  event  flag  30  is  used 
for  internal  synchronization.  If  iefn  is  an  event  flag,  the 
selected  event  flag  is  set  as  each  buffer  is  filled.  Note  that 
event  flag  29  is  reserved  for  use  by  the  LPAll-K  support  routines 
for  internal  synchronization.  If  iefn  is  greater  than  9f>,  it  is 
considered  to  be  a  completion  routine  that  will  be  called  with  a 
JSR  PC.  Such  routines  must  return  with  an  RTS  PC  instruction  (or 
a  FORTRAN  RETURN  Statement) . 
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FORTRAN  completion  routines  must  not  contain  any  of  the 
following: 

•  Any  I/O  through  the  FORTRAN  run-time  system 

e  Any  use  of  virtual  arrays 

e  Any  use  of  floating-point  operations 

e  Any  errors,  since  error  reporting  ia   done  through  the   FORTRAN 
run-time  system 

e  Anything  else  that  may  change  the  FORTRAN  impure  area 

Any  of  the  above  may  result  in  fatal  task  errors  or  unpredictable 
resul ts. 

If  multiple  sweeps  are  initiated,  the  user  task  should  specify 
different  event  flags.  This  limitation  cannot  be  enforced  by  the 
LPAll  driver. 

Idelay 

The  delay  from  start  event  (DRll-K)  until  the  first  sample  in 
irate  units.  A  minimum  delay  of  ISO  microseconds  is  required 
(not  verified  by  the  LPAll  driver).  This  feature  is  supported  in 
mul  ti  requei^t  mode  only. 

ichn 

The  first  channel  number.   Default  is  channel  number  0. 

nchn 

The  number  of  channel!!.   Default  is  one  channel. 

Ind 

Receives  a  success  or  failure  code  as  follows: 

1   indicates  that  the  sweep  was  successfully  initialized. 

0   indicates  an  illegal   argument   list,   or   SETIBF  was  not 
called  prior  to  this  call. 

-1  indicates  a  QIO  directive   failure.    The  directive  error 
code  is  placed  in  lOSB(l)  in  IBUF. 

NOTE 

The  ind  parameter  is  not  supported  by  the  K-series 
support  routines.  If  compatibility  with  K-series 
routines  is  desired,  this  parameter  must  be 
ignored . 
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21.3.1.6  DISWPt  Initlat*  Synchronoua  Digital  Input  Swaap  -  The  DISWP 
routine  initiates  a  synchronous  digital  input  sweep  through  a  DRll-K. 
It  can  be  called  in  multirequest  mode  only. 

The  DISWP  call  is  as  follows: 

CALL  DISWP  (ibuf ,lbuf ,(nbuf1 , [mode] , [idwein , (iefnl , [Idelayl  , 
[iunit] ,fnchn1 , [indl ) 


ibuf 


A  40-word  array  initialized  by  the  SETIBF  routine.   The  first  two 
words  of  the  array  are  the  I/O  status  block  (lOSB). 


Ibuf 


The  size  in  words  of  each  data  buffer.   All  data  buffers  must   be 
equal  in  size  and  Ibuf  must  be  greater  than  5. 


nbuf 


The  number  of  buffers  to  be  filled.  If  nbuf  is  0  or  defaulted, 
indefinite  sampling  occurs.  The  STPSWP  routine  is  used  to 
terminate  indefinite  sampling. 


•od* 


The  sampling  options.  The  default  is  0.  The  plus  signs  (-f) 
preceding  the  mode  bit  values  listed  below  indicate  that  they  are 
independent  and  can  be  added  or  ORed  together.  All  bit  values 
not  listed  below  are  reserved. 

The  following  values  can  be  specified; 

0      Immediate  start.   This  is  the  default  mode. 

••■512  External  trigger.  The  input  sampling  will  be  triggered 
by  interrupts  generated  by  the  DRll-K's  external 
control  lines,  or  its  input  bits  if  they  are  interrupt 
enabled . 

■fl024   Time  stamped  sampling  with  Clock  B.    The  double   word 

consists   of  one  data  word  followed  by  the  value  of  the 

16-bit  clock  at   the   time   of   the   sample.    I0SB(2) 

contains  the  number  of  2-word  samples  in  the  buffer. 

•f2048  Event  marking.  LAMSKS  must  be  called  to  specify  an 
event  mark  word  and  an  event  mark  mask. 

•«-409fi  Start  method.  If  specified,  digital  input  start.  If 
clear,  immediate  start.  LAMSKS  must  be  called  to 
specify  a  digital  start  channel  and  a  digital  start 
mask.  The  digital  start  channel  need  not  differ  from 
the  input  channel  (iunit). 

+16384  Data   overrun   NON-FATAL/FATAL.    If    selected,    data 

overrun     is   considered    nonfatal.     The    LPAll-K 

automatically  fills  buffer  0.   (See  Section  21.4  for   a 

discussion  of  buffer  management.) 
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idw«ll 


The  number  of  clock  overflows  (pulses)  between  data  sample 
sequences.  As  an  example,  if  idwell  is  20  and  nchn  is  3,  the 
following  occurs:  After  20  pulses,  one  channel  is  sampled  on 
each  of  the  next  three  pulses.  Then,  no  sampling  takes  place  for 
the  next  20  pulses.  In  multirequest  mode,  this  facility  permits 
different  sample  rates  for  the  same  hardware  clock  rate  and 
preset. 

If  compatibility  with  K-series  support  routines  is  desired,  the 
user  task  must  first  establish  the  clock  preset  by  calling  the 
CLOCKA  routine.  The  default  value  (1)  for  the  idwell  parameter 
in  the  sweep  start  command  must  be  used.  For  the  K-series,  this 
procedure  sets  the  rate  as  desired.  For  the  LPAll-K,  this 
procedure  results  in  idwell  in  the  sweep  call  defaulting  to  1, 
thus  yielding  the  same  clock  rate. 

NOTE 

This  parameter  is  called  iprset  in  the  K-series  support 
routines  described  in  Chapter  22.  Its  function  is 
different  from  the  idwell  parameter  described  here. 


lefn 


An  event  flag  number  (1  to  28,  30  to  9fi) ,  or  the  name  of  a 
completion  routine,  or  0.  If  default  or  a  value  of  0  is 
specified  for  iefn,  event  flag  30  is  used  for  internal 
synchronization.  If  iefn  is  a  valid  event  flag,  the  selected 
event  flag  is  set  as  each  buffer  is  filled.  Note  that  event  flag 
29  is  reserved  for  use  by  the  LPAll-K  support  routines  for 
internal  synchronization.  If  iefn  is  greater  than  96,  it  is 
considered  to  be  a  completion  routine  that  will  be  called  with  a 
JSR  PC  Such  routines  must  return  with  an  RTS  PC  instruction  (or 
a  FORTRAN  RETURN  statement)  . 

FORTRAN  completion  routines  must  not  contain  any  of  the 
following : 

•  Any  I/O  through  the  FORTRAN  run-time  system 

•  Any  use  of  virtual  arrays 

•  Any  use  of  floating-point  operations 

•  Any  errors,  since  error  reporting  is  done  through  the   FORTRAN 
run-time  system 

•  Anything  else  that  may  change  the  FORTRAN  impure  area 

Any  of  the  above  may  result  in  fatal  task  errors  or  unpredictable 
resul ts. 

If  multiple  sweeps  are  initiated,  the  user  task  should  specify 
different  event  flags.  This  limitation  cannot  be  enforced  by  the 
LPAll  driver. 


Idelay 


The  delay  from  start  event  (DRll-K)  until   the   first   sample   in 
irate  units.   Default  or  0  indicates  no  delay. 


21-13 


LABORATORY  PERIPHERAL  ACCELERATOR  DRIVER 

iunit 

The  DRU-K  unit  number.   Default  is  unit  number   0.    Values   0-4 
are  valid. 

nchn 

The  number  of  channels.   The  LPAll-K  treats  each   DRll-K   in   its 
configuration  as  one  channel.   Default  is  1  channel. 

ind 

Receives  a  success  or  failure  code  as  follows: 

1   indicates  that  the  sweep  was  successfully  initialized. 

0   indicates  an  illegal   argument   list,   or   SETIBF  was   not 
called  prior  to  this  call. 

-1  indicates  a  010  directive   failure.    The  directive  error 
code  is  placed  in  lOSB(l)  in  IBUF. 

NOTE 

The  nchn  and  f nd  parameters  are  not  supported  by 
the  K-series  support  routines.  If  compatibility 
with  K-series  support  routines  is  desired,  these 
last  two  parameters  must  be  ignored. 


?1.3.1.7  DOSWP:  Initiate  Synchronous  Digital  Output  Sweep  -  The  DOSWP 
routine  initiates  a  synchronous  digital  output  sweep  through  a  DRll-K. 
It  can  be  called  in  multirequest  mode  only. 

The  DOSWP  call  is  as  follows: 

CALL  DOSWP  (ibuf.lbuf , fnbufl , [model , fidwelll , fiefnl ,ldelay, 
[iunitl  , fnchn] , find] ) 


ibuf 


Ibuf 


nbuf 


A  40-word  array  initialized  by  the  SETIBF  routine.   The  first  two 
words  of  the  array  are  the  I/O  status  block  (lOSB). 


The  size  In  words  of  each  data  buffer.   All  data  buffers  must   be 
equal  in  size  and  Ibuf  must  be  greater  than  S. 


The  number  of  buffers  to  be  emptied.  If  nbuf  is  0  or  default, 
indefinite  emptying  occurs.  The  STPSWP  routine  is  used  to 
terminate  indefinite  emptying. 
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nod* 

The  start  criteria. 

The  following  values  can  be  specified  in  the  high-order   byte  of 
mode : 

0      Immediate  start.   This  is  the  default  mode. 

+512   External   trigger.    The  output   sampling  will   be 

triggered   by   interrupts  generated   by  the  DRll-K's 

external  control  lines  or  its  input  bits   if  they  are 
interrupt  enabled. 

+4096  Start  method.  If  set,  digital  input  start.  If  clear, 
immediate  start.  LAMSKS  must  be  called  to  specify  a 
digital  start  channel  and  a  digital  start  mask.  The 
digital  start  channel  need  not  differ  from  the  output 
channel  ( iuni t)  . 

+lfi384  Data  overrun  NON-FATAL/FATAL.  If  selected,  data 
overrun  is  considered  nonfatal.  The  LPAll-K 
automatically  fills  buffer  0.  (See  Section  21,4  for  a 
discussion  of  buffer  management.) 


idwell 


The  number  of  clock  overflows  (pulses)  between  data  sample 
sequences.  For  example,  if  idwell  is  20  and  nchn  is  3,  the 
following  occurs:  After  20  pulses,  one  c"  annel  is  activated  on 
each  of  the  next  three  pulses.  Then,  no  output  takes  place  for 
the  iiext  20  pulses.  In  multirequest  mode,  this  facility  permits 
different  output  rates  for  the  same  hardware  clock  rate  and 
preset. 

If  compatibility  with  K-series  support  routines  is  desired,  the 
user  task  must  first  establish  the  clock  presec  by  calling  the 
CLOCKA  routine.  The  default  value  (1)  for  the  idwell  parameter 
in  the  sweep  start  command  must  be  used.  For  the  K-series,  this 
procedure  sets  the  rate  as  desired.  For  the  LPA11~K,  this 
procedure  results  in  idwell  in  the  sweep  call  defaulting  to  1, 
thus  yielding  the  same  clock  rate. 

NOTE 

This  parameter  is  called  iprset  in  the  K-series  support 
routines  described  in  Chapter  22.  Its  function  is 
different  'rom  the  idwell  parameter  described  here. 


iefn 


An  event  flag  number  (1  to  28,  30  to  96),  or  the  name  of  a 
completion  routine,  or  0.  If  default  or  a  value  of  0  is 
specified  for  iefn,  event  flag  30  is  used  for  internal 
synchronization.  If  iefn  is  a  valid  event  flig,  the  selected 
event  flag  is  set  as  each  buffer  is  emptied.  Note  that  event 
flao  29  is  reserved  for  use  by  the  LPAll-K  support  routines  for 
internal  synchronization.  If  iefn  is  greater  than  96,  it  is 
considered  to  be  a  completion  routine  that  will  be  called  with  a 
JSR  PC.  Such  routines  must  return  with  an  PTS  PC  instruction  (or 
a  FORTRAN  RETURN  statement)  . 
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FORTRAN  conplction  routines  must  not  contain  any  of  th* 
following : 

•  Any  I/O  through  the  POR'^KAN  run-tine  system 

•  Any  use  of  virtual  arr«ys 

•  Any  use  of  floating-point  operations 

•  Any  errors,  since  error  reporting  is  done  through  the   FORTRAN 
run-time  system 

•  Anything  else  that  nay  change  the  FORTRAN  impure  area 

Any  of  the  above  nay  result  in  fatal  task  errors  or  unpredictable 
results. 

If  multiple  sweeps  are  initiated,  the  user  task  should  specify 
different  event  flags.  This  limitation  cannot  be  enforced  by  the 
LPAll  driver. 


Idelay 


The  delay  from  start  event  (DRll-K)  until  the  first  sample  in 
irate  units.  A  minimum  delay  of  ISO  microseconds  is  required 
(not  verified  by  the  LPAll  driver). 


iunit 


nchn 


ind 


The  DRll-K  unit  number.   Default  is  unit  number   0.    Values   0-4 
are  valid. 


The  number  of  channels.   The  LPAll-K  treats  each   DRll-K   In   its 
configuration  as  one  channel.   Default  is  one  channel. 


Receives  a  success  or  failure  code  as  follows: 

1   indicates  that  the  sweep  was  successfully  initiated. 

0   indicates  an  illegal   argument   list,   or   SETIBF  was   not 
called  prior  to  this  call. 

-1  indicates  a  010  directive   failure.    The  directive  error 
code  Is  placed  in  lOSB(l)  in  IBUF. 


NOTE 

The  nchn  and  ind  parameters  are  not  supported  by 
the  K-series  support  routines.  If  compatibility 
with  K-series  support  routines  is  desired,  these 
last  two  parameters  must  be  ignored. 


® 
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21.3.1.8  PLT16t   Convert  Unsigned   Integer  to  a  Real   Constant  -  The 

FLTlfi   routine  converts  an  unsigned  Ifi-bit  integer  to  a  real  constant 
(REAL*4) .   It  can  be  invoked  as  a  subroutine  or  a  function  as  follows: 

CALL  FLT16  (ival,val) 

or 

val-FLT16(Ivair  ,vall ) 

ival 

An   unsigned    Ifi-bit    integer. 

val 

The  converted  (REAL*4)  value. 


21.3.1.9   IBPSTS;  Get  Buffer  Sta":u8  -  The    TBFSTS   routine    returns 
information  on  buffers  being  used  in  a  sweep. 

The  IBFSTS  call  is  as  follows: 

CALL  IBFSTS  (ibuf,istat) 

ibuf 

The  40-word  array  specified  in  the  call  that  initiated  a  sweep. 


istat 


An  array  with  as  many  elements  as  there  are  buffers  involved  in 
the  sweep.  The  maximum  is  8.  IBFSTS  fills  each  element  in  the 
array  with  the  status  of  the  corresponding  buffer.  The  possible 
status  codes  are  as  follows: 

+2  indicates  that  the  buffer  is  in  the  device  queue.  That 
is,  RLSBUF  has  been  called  for  this  buffer. 

+1  indicates  that  the  buffer  is  in  the  user  task  queue. 
That  is,  it  is  full  of  data  (for  input  sweeps)  or  is 
available  to  be  filled  (for  output  sweeps). 

0  indicates  that  the  status  of  the  buffer  is  unknown. 
That  is,  it  is  not  the  current  buffer  nor  is  it  in 
either  the  device  or  the  user  queue. 

-1     indicates  that  the  buffer  is  currently  in  use. 


21.3.1.10  IGTBUF:  Return  Buffer  Number  -  The  IGTBUF  routine  returns 
the  number  of  the  next  buffer  to  use.  This  routine  should  be  called 
by  user-task  completion  routines  to  determine  which  is  the  next  buffer 
to  access.  It  should  not  be  used  if  an  event  flag  was  specified  in 
the  sweep-initiating  call;  if  an  event  flag  was  specified,  use  the 
IWTBUF  routine. 
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IGTBUP  can  be  invoked  as  a  subroutine  or  a  function  as  follows: 

CALL  IGTBUP  { ibuf , ibuf no) 
or 

ibufno-IGTBUFdbuf  r  ,lbufnol  ) 

Ibuf 

The  40-word  array  specified  in  the  call  that  initiated  a  sweep. 

ibufno 

Receives  the  number  of  the  next  buffer  to  access.   If  there  is  no 
buffer  in  the  queue,  ibufno  contains  -1. 

On  the  return  from  a  call  to  IGTBUP,  the  following   are   the   possible 
combinations  of  ibufno  and  lOSB  contents: 


ibufno    lOSB(l) 

n      400(8) 
n       1 


-1 
-1 
-1 


0 
1 


I0SB(2) 

(Word  count) 
(Word  count) 


RSX-llM       LPAll-K 
error  code(in)  error  code(B) 


Explanation 

Normal   buffer    complete. 

Buffer  complete.  Sweep 
terminated.  There  may  be 
additional  buffers  in  the 
queue  filled  and  ready  for 
processing . 

No  buffers  in  queue. 
Request  still  active. 

No  buffers  in  queue.  Sweep 
terminated. 

No  buffers  in  queue. 
Sweep  terminated  due  to 
error  condition.  (Refer  to 
Section  21.3.3  for  error 
code  summary.)  Note  that 
the  error  is  not  returned 
until  there  are  no  more 
buffers  in  the  user  queue. 


21.3.1.11  INXTBP:  Set  Next  Buffer  -  The  INXTBP  routine  alters  the 
normal  buffer  selection  algorithm.  It  allows  the  user  task  to  specify 
the  number  of  the  next  buffer  to  be  filled  or  emptied. 

INXTBP  can  be  invoked  as  a  subroutine  or  a  function  as  follows: 

CALL  INXTBP  ( ibuf , ibuf no f ,  ind] ) 
or 

lnd-lNXTBP(ibuf ,ibufnor,lndl ) 
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Ibuf 

The  40-word  array  sp«cifi«d  in  th«  call  that  initiated  a  sweep. 

ibufno 

The  number  of  the  next  buffer  the  user  wants  filled   or   emptied. 
The  buffer  must  already  be  in  the  device  queue. 

ind 

Receives  an  indication  of  the  result  of  the  operation: 

0  indicates  that  the  specified  buffer  was  not  in   the  device 
queue. 

1  indicates  that  the  next  buffer  was  successfully  set. 


21.3.1.12  IWTBUP:  Wait  for  Buffer  -  The  IWTBUP  routine  allows  a  user 
task  to  wait  for  the  next  buffer  to  fill  or  empty.  It  should  be  used 
in  conjunction  with  the  specification  of  an  event  flag  in  the 
sweep-initiating  call.  This  routine  should  not  be  used  if  a 
completion  routine  was  specified  in  the  call  to  initiate  a  sweep; 
when  event  flags  are  specified,  use  the  IGTBUP  routine. 

IWTBUP  can  be  invoked  as  a  subroutine  or  a  function  as  follows: 

CALL  IWTBUP  (ibuf ,riefnl .ibufno) 


ibuf no«IWTBUF { ibuf, ( ief n] , [ ibufno) ) 

ibuf 

The  40-word  array  specified  in  the  call  that  initiated  a  sweep. 

lefn 

The  event  flag  on  which  the  task  will  wait.  This  should  be  the 
same  event  flag  as  that  specified  in  the  sweep-initiating  call. 
If  iefn  equals  0  or  default,  event  flag  30  is  used. 


ibufno 


Receives  the  number  of  the  next  buffer  to  be  filled  or  emptied  by 
the  user  task. 
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On  the  return  from  a  call  to  IWTBUF,  the  following 
combinations  of  ibufno  and  lOSB  contents! 


are   the   possible 


Ibufno 


n 
n 


-1 


-1 


I08B ( 1 ) 

400(8) 
1 


1088(2) 
(word  count) 
(word  count) 


RSX-llM       LPAll-K 
error  code(lO)  error  code(8) 


Explanation 

Normal   buffer   complete. 

Buffer  complete.  Sweep 
terminated.  There  may  be 
additional  buffers  in  the 
queue  filled  and  ready  for 
processing. 


No   buffers    in 
Sweep  terminated. 


queue. 


No  buffers  in  queue. 
Sweep  terminated  due  to 
error  condition.  (Refer 
to  Section  21.3.3  for 
error  code  summary.)  Note 
that  the  error  is  not 
returned  until  there  are 
no  more  buffers  in  the 
user  queue. 


21.3.1.13  LAMSKSt  Set  Masks  Buffer  -  The  LAMSKS  routine  initializes  a 
user  buffer  containing  a  LUN,  a  digital  start  mask  and  event  mark 
mask,  and  channel  numbers  for  the  two  masks.  The  routine  then  assigns 
the  LUN.  Each  DRll-K  is  considered  to  be  one  channel.  Each  channel 
has  both  input  and  output  capabilities. 

LAMSKS  must  be  called  if  digital  input  starting  or  event  marking  is  to 
be  utilized,  or  if  a  LUN  other  than  the  default  LUN  7  will  be  assigned 
to  LAO.  LAMSKS  must  also  be  called  if  multiple  LPAll-Ks  are  being 
used.  If  LAMSKS  is  to  be  called,  it  must  be  called  prior  to  calling 
SETIBF.  Unlike  SETIBF,  LAMSKS  does  not  have  to  be  called  before  each 
sweep  initiation  unless  one  or  more  parameters  are  to  be  changed. 

The  LAMSKS  call  is  as  follows: 

CALL  LAMSKS  (lamskb, [lun] , ( iuni t] , f idsc) , f iemc] , f idsw] , 
[iemw],[indl) 


lamskb 

A  4-word  array, 


lun 


A  logical  unit  number.   Default  LUN  is  7. 
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iunit 

The  physical  unit  number  of  the  LPAll-K.   Default   physical   unit 
number  is  LAO. 

Idsc 

The  digital  start  word  channel.   Default  is  channel  0. 

iemc 

The  event  mark  word  channel.   Default  is  channel  0. 

idsw 

The  digital  start  word  mask.   Default  is  0  (disable  digital  input 
starting) . 

iemw 

The  event  mark  word  mask.   Default  is  0  (disable  event  marking). 


ind 


Receives  a  success  or  failure  code  as  follows: 

1   Indicates  successful  initialization. 

0   indicates  an  Illegal  argument  list. 

-n  indicates  a  LUN  assignment  failure.    n   is   the  directive 
error  code. 


NOTE 

If  compatibility  with  K-series  support  routines   is 
des'.red,  ignore  this  parameter. 

For  a  discussion  of   event   marking   and   digital   starting,   see   the 
LPAll-K  Laboratory  Peripheral  Accelerator  User's  Guide. 


21.3.1.14  RLSBUP:  Release  Data  Buffer  -  The  RLSBUF  routine  declares 
one  or  more  buffers  free  for  use  by  the  Interrupt  service  routine. 

The  RLSBUF  routine  must  be  called  to  release  buffer(s)  to  the  device 
queue  before  the  sweep  Is  Initiated.  The  device  queue  must  always 
contain  at  least  one  buffer  to  maintain  continuous  sampling. 
Otherwise,  buffer  overrun  occurs  (see  Section  21.4  for  a  discussion  of 
buffer  management).  Note  that  RLSBUF  does  not  verify  whether  the 
specified  buffers  are  already  ir  a  queue. 
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Th*  RLSBUP  call  is  at    follows: 

CA[    LSBUP  (Ibuf ,[lndl ,n0[,nl...,n71) 

ibuf 

Th«  40-word  array  specified  in  the  call  that  initiated  a  sweep. 

Ind 

Receives  a  success  or  failure  code  as  follows: 

0  indicates  illegal  buffer  number  specified,  illegal  number 
of  buffers  specified,  or  a  double  buffer  overrun  has  been 
detected . 

1  indlcat«»s  buffer(s)  successfully  released. 

nO,nl,etc. 

The  numbers  (0-7)  of  the  buffers  to  be  released.    A  maximum  of 
eight  can  be  specified. 

21.3.1.15  RMVBUF:  Remove  Buffer  from  Device  Queue  -  The   RMVBUF   rou- 
tine removes  a  buffer  from  the  device  queue. 

The  RM''3UF  call  is  as  follows: 

CALL  RMVBUF  ( ibuf ,n [, ind] ) 

ibuf    : 

The  40-word  array  specified  in  the  call  that  initiated  a  sweep. 

n  :''■'■'  /  '  ',."  .  :  '.  ■':  ..  _ 

The  number  of  the  buffer  to  remove.  •' 

ind 

Receives  a  success  or  failure  code  as  follows: 

0  indicates  that  the  specified  buffer  was  not  in  the  device 
queue. 

1  indicates  that  the  specified  buffer  was  removed  from  the 
queue. 


21.3.1.16  SETADC:  Set  Channel  Xnfokrmatlor  -  The  SETADC  routine 
establishes  channel  start  and  increment  information  for  all  rweeps. 
The  SETIBF  routine  must  be  called  to  initialize  the  40-word  array 
(ibuf)  before  SETADC  is  called. 
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If,  in  the  call  to  SETADC,  nchn  Is  1  or  inc  is  0,  the  single  "hannel 
bit  will  be  set  in  the  mode  word  of  the  start  RDA  when  the  sweep  start 
routine  is  (Tailed. 

SETADC  can  be  invoked  as  a  subroutine  or  a  function  as  follows: 

CALL  SETADC  ( ibuf ,[ i flagl ,[ ichnl , (nchn] ,[ inc] ,[ ind] ) 

ind  -  ISTAOC(ibuf ,(iflag] ,[ichn] , [nchn] , [inc] , [ind] ) 

ibuf 

A  40-word  array  initialized  by  the  SETIBF  routine. 


iflag 


ichn 


Ignored.   It  is  included  for  compatibility  with  K-series  support 
routines. 


The  first  channel  number.  Default  is  0.  If  inc  equals  0  (or 
default),  ichn  is  the  address  of  a  random  channel  list.  A  random 
channel  list  is  an  array  of  n  elements,  where  each  element  is  a 
channel  number.  The  final  element  must  have  bit  15  set  to 
indicate  the  end  of  the  list. 


nchn 


lilt 


ina 


The  number  of  samples  to  be  taken  per  sequence.   Default   is  one 
sample. 


The  channel  increment.  Default  is  1.  The  user  should  specify  an 
increment  of  2  for  differential  A/D  input.  If  inc  equals  0,  ichn 
is  an  array  of  random  channels  to  receive  input. 


Receives  a  success  or  failure  code  as  follows: 

0  indicates  an  illegal  channel   number   or   SETIBF  was  not 
called  prior  to  the  SETADC  call. 

1  indicates  successful  recording  of  channel   information   for 
the  sweep  call. 


21.3.1.17  SBTIBP:  Set  Array  for  Buffered  Sweep  -  The  SETIBF  routine 
initializes  an  array  required  by  buffered  sweep  routines.  The  SETIBF 
routine  must  be  called  before  every  call  to  a  buffered  sweep  routine. 
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The  SETIBF  call  la  as  followst 

CALL  SETIBP  ( ibuf , [ ind] , [lanskb] ,buf 0 [ ,buf 1 . . .buf 7] ) ■ 

ibuf 

A  40-word  array. 

Ind 

Receives  a  success  or  failure  code  as  follows: 

0  indicates  a  parameter  or  buffer  error. 

1  indicates  the  array  was  successfully  Initialized. 


lanskb 


The  name  of  a  4-word  array.  This  array  allows  the  use  of 
multiple  LPAll-Ks  within  the  same  program,  since  the  LUN  is 
specified  in  the  first  word  of  the  array.  Refer  to  the 
dr.  script  ion  of  the  LAMSKS  routine. 

If  compatibility  with  K-series  software  is  desired,  the  default 
(LUN  7)  lamskb  parameter  should  be  used,  and  LUN  7  will  be 
assignel  to  LAO;  in  the  task-build  command  file  for  the  user 
task. 

bufO,  etc. 

The  name  of  a  buffer.  A  maximum  of  eight  buffers  can  be 
specified.  Any  buffer  names  in  excess  of  eight  are  ignored.  At 
least  two  buffers  must  be  specified  to  maintain  continuous 
sampling. 

Each  buffer  specified  in  the  call  to  SETIBF  is  assigned  a  number 
ranging  from  0  to  7. 

The  assignment  of  these  numbers  is  based  on  the  order  in  which  buffer 
names  appear  in  the  argument  list.  The  first  buffer  whose  name 
appears  in  the  list  is  assigned  number  0,  the  second  i"-  assigned 
number  1,  and  so  forth.  In  all  subsequent  calls  to  other  routines 
involving  the  set  of  buffers  specified  in  a  call  to  SETIBF,  these 
numbers,  rather  than  names,  are  used  to  refer  to  particular  buffers. 


21.3.1.18   STPSWP:  Stop  Sweep  -  The  STPSWP  routine  stops  a  sweep   that 
is  in  progress. 

The  STPSWP  call  is  as  follows: 

CALL  STPSWP  (ibuf r,iwhen] , [ind]) 
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Ibuf 

The  40-wor(]  array  specified  in  the  call  that  initiated  a  sweep. 

Iwhen 

Specifies  when  to  stop  the  sweep: 

0  stops  the  sweep,  immediately  aborting  the  sweep.  This  is 
the  default  stop  method.  The  sweep  will  be  stopped 
asynchronously  by  the  LPAll-K  hardware.  When  lOSB(l) 
equals  1,  the  sweep  has  been  stopped.  Call  IWTBUF 
continously  after  calling  STPSWP  until  the  sweep  has 
actually  been  stopped.  When  stopping  (aborting)  a  sweep  in 
this  manner,  the  data  contents  of  the  current  data  buffer 
cannot  be  guaranteed. 

■fn  (any  positive  value)  stops  the  sweep  at  the  end  of  the 
current  buffer.  This  is  considered  to  be  the  normal  means 
for  stopping  a  sweep. 

-n  (any  negative  value)  is  reserved.   (Do  not  use.) 


Receives  a  success  or  failure  code  as  follows: 

1   indicates  that  the  sweep  will   be   stopped   (at   the   time 
indicated  by  iwhen) . 

0   indicates  an  illegal  argument  list. 

-n  is  a  directive  error  code  indicating  that   the   stop  sweep 
010  failed. 


21.3.1.19  XRATE:  Compute  Clock  Rate  and  Preset  -  The  XRATE  routine 
allows  the  user  task  to  compute  a  clock  rate  and  preset.  The  clock 
rate  divided  by  the  clock  preset  yields  the  desired  dwell  (intersample 
interval) . 

NOTE 

The  XRATE  routine  can  be  used  only  on 
systems  that  have  a  FORTRAN  or 
BASIC-PLUS-2  compiler.  This  module  is 
not  Included  with  the  other  LPAll-K 
support  routines  in  object  module 
format.  Rather,  it  is  included  in 
source  code  format  with  the  K-series 
source  modules  in  [45,101  on  the  system 
disk. 
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XRATE  can  b«  invoked  as  a  subroutine  or  a  function  as  follows: 

CALL  XRATE  (dwell , irate, iprset , i flag) 
or 

adwell  •  XRATB(dwell, irate, iprset,iflag) 

dwell 

The  intersample  time  desired  by  the  user.   The  time  is  expressed 
in  decimal  seconds  (REAL*4). 

irate 

Receives  the  computed  clock  rate  as  a  value  from  1  to  5, 

iprset 

Receives  the  clock  preset. 


Iflag 


Specifies  whether  the  computation  is  intended  for  Clock  A  or 
Clock  B: 

0   indicates  the  computation  is  for  Clock  A. 
nonzero  indicates  the  computation  is  for  Clock  B. 


•dwell 


The  actual  dwell  rate  for  the  clock  based  on  the  irate  and  iprset 
parameters. 


21.3.2  NACRO-11  Interface 

The  MACRO-11  interface  to  the  LPAll-K  consists  of  either  the  callable 
routines  described  in  Section  21.3.1  or  a  set  of  device-specific  QIO 
functions. 


21.3.2.1  Accessing  Callable  LPA11~K  Support  Routines  -  MACRO-11 
programmers  access  the  LPAll-K  support  routines  through  either  of  two 
techniques: 

1.  The  standard  subroutine  linkage  mechanism  and  the  CALL  op 
code 

2.  Special-purpose  macros  that  generate  an  argument  list  and 
invoke  a  subroutine 

These  techniques  are  described  In  the  following  subsections. 
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21.3.2.2  Standard  Subroutine  Linkage  and  CALL  Op  Coda  -  LPAll-K 
routines  can  be  accessed  through  use  of  the  standard  subroutine 
linkage  mechanism  and  the  CALL  op  code.  The  format  of  this  procedure 
1st 

.PSCCT  code 

MOV      targllst.RS   /ARGUMENT  ADDRESS  TO  R5 

CALL     Isubr         ;CALL  LPAll-K  ROUTINE 

.PSECT  data 
argllst:   .BYTE    narg,0        /NUMBER  OF  ARGUMENTS 

.WORD   addrl         ; FIRST  ARGUMENT  ADDRESS 


.WORD    addrn         ;LAST  ARGUMENT  ADDRESS 

In  this  sample,  the  two  PSECT  directives  are  shown  only  to  Indicate 
the  noncontlgulty  of  the  code  and  data  portions  of  the  linkage 
mechanism.  Within  the  argument  list,  any  argument  that  is  to  be 
defaulted  must  be  represented  by  a  -1  address  (that  is,  177777(8)). 


21.3.2.3  Special-Purpose  Macros  -  To  facilitate  the  calling  of 
LPAll-K  support  routines  from  a  MACRO-11  program,  two  macros  are 
provided  in  file  [45,10] LABMAC. MAC.   These  macros  are: 

1.  INITS 

2.  CALLS 

INITS  is  an  initialization  macro.  It  must  be  invoked  at  the  beginning 
of  the  MACRO-11  source  module. 

CALLS  invokes  an  LPAll-K  support  routine.  The  format  of  this  macro 
call  is  as  follows! 

CALLS  Isubr ,<argl, ... ,argn> 

Isubr 

The  name  of  an  LPAll-K  support  routine. 

•rgl,  and  so  forth 

Arguments  to  be  formatted  into  an  argument  list  and  passed  to  the 
routine.  Each  argument  can  be  either  a  symbolic  name  or  a 
constant  (interpreted  as  a  positive  decimal  number)  or  can  be 
defaulted. 
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An  •x«Mpl«  showing  th«  ut»  of  those  macros  is  as  followsi 


.TTTLE  EXAMPLE 

.IDENT  /Ol.OO/ 

IBUPt    .BLKW  40. 

ISTAT:   .BLKW  5 

INITS  ,  INITIALIZATION 


START: 


t 

;  FIND  STATUS  OF  5  SWEEP  BUFFERS 

;  BEING  USED  IN  CURRk.NT  SWEEP 

I 

CALLS    IBFSTSdBUF,  ISTAT) 

4 


• 


.END 


START 


71.3.2.4  Dovico-Spoclfic  010  Functions  -  Table  21-2  lists  tho 
device-specific  functions  of  the  010  system  directive  macro  that  dre 
available  for  the  LPAll-K.  Programmers  using  these  functions  are 
entirely  responsible  for  buffer  management  (refer  to  Section  21.4)  as 
well  as  all  other  interfaces  (for  example,  the  request  descriptor 
array).  Little  (if  any)  performance  improvement  over  the  use  of 
FORTRAN  support  routines  can  be  expected  by  using  QIOs.  Therefore,  it 
Is  recommended  that  routines  described  in  Section  21.3.1  be  used. 


Table  21-2 
Device-Specific  010  Functions  for  the  LPAll-K 


010  Function 

Purpose 

,        lO.CLK 
10. INI 
lO.LOD 
lO.STA 
lO.STP 

Start  clock 
Initialize  LPAll-K 
Load  microcode 
Start  data  transfer 
Stop  request 

• 
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The  MACRO-H  programmer  must  set  up  the  appropriate  Request  Descriptor 
Array  (RDA)  before  the  corresponding  QIO  request  is  Issued.  In  the 
case  of  the  lO.STA  function  (start  data  transfer?,  the  RDA  is  set  up 
with  buffer  virtual  addresses.  The  LPAll-K  driver  address  checks  and 
relocates  these  buffers,  changing  them  from  single-word  to  double-word 
addresses.  The  RDA  is  fully  described  in  the  source  code  of  the 
driver. 


21.3.2.5  lO.CLK  -  Th(«  lO.CLK  function  writes  an  image  into  the 
LPA)1-K  real-time  clock  control  register  and  issues  a  clock  start 
command.   The  format  of  the  QIO  request  is: 

0IO$C  lO.CLK,. . . ,<mode,ckcsr,preset> 

mode  , 

The  mode. 
'■  *  « 

ckcsr      » 

The  image  to  be  written  into  the  clock  control  register.  To 
achieve  the  function  of  clock  rate  -1  (see  Section  21.3.1.2)  for 
Clock  A  only,  set  a  clock  rate  of  0  and  set  the  Schmitt  Trigger  1 
Interrupt  Enable  bit  in  the  Clock  A  Status  Register. 

»   ■.         ' 
preset 

The  clock  preset.  » 

21.3.2.fi  10. INI  -  The  10. INI  function  initializes  the  LPAll-K.  The 
task  issuing  the  QIO  request  must  be  privileged.  The  format  of  the 
request  is  as  follows: 

QIO$C  IO.INI,...,<irbut',278.> 

irbuf      '    ,  ♦    >   ^ 

A  buffer  containing  an  LPAll-K  initialize  RDA.  The  buffer  size 
must  be  at  leapt  278  (10)  bytes. 


21.3.2.7  lO.LOD  -  The  lO.LOD  function  loads  a  buffer  of  LPAll-K 
microcoje.  The  issuing  task  must  be  privileged.  The  function 
verifies  that  there  are  no  active  users  for  the  LPAll-K  and  resets  the 
hardware.  It  then  loads  and  verifies  the  microcode,  starts  the 
LPAll-K,  and  enables  interrupts.  The  function  returns  to  the  issuing 
task  when  the  Ready  Interrupt  is  posted. 
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Th«  foraat  of  the  010  request  for  the  lO.LOD  function  Is  a*  follows: 
QIOSC  lO.LOD, . ..  ,<inbuf  ,2048.> 


■buf 


A  buffer  containinq  microcode  to  be  loaded.   The  buffer  size  must 
be  2048(10)  bytes. 


21.3.2.8   lO.STA  -  The  lO.STA  function  issues  an  LPAll-K  data  transfer 
start  command.   The  format  of  the  010  request  is: 


QIOSC  IO.STA,...,<butptr,40.> 

bufptr 

A  pointer  to  a  buffer  containing  an   LPAll-K   sample   start   RDA. 
The  buffer  size  must  be  at  least  40(10)  bytes. 

The  subfunction  codes  defined  for  the  lO.STA  function  are: 

Bit  0  <•  0    indicates  that  an  AST  is  to  be  generated   for   every 
buffer  (if  an  AST  is  specified). 

Bit  0*1    indicates  that  an  AST  is  to   be  generated   only   for 
exception  conditions. 


21.3.2.9  lO.STP  -  The  lO.STP  function  stops  a  data  transfer  request. 
The  issuing  task  must  be  the  same  task  that  initiated  the  data 
transfer.   The  format  of  the  QIO  request  is  as  follows: 

OIOSC  lO.STP,. . . ,<userid> 


userid 


The  index  number  associated  with  the  user  whose  request  is  to  be 
stopped . 


21.3.3  The  I/O  Status  Block  (lOSB) 

Each  active  sweep  must  have  its  own  I/O  status  block.  The  I/O  status 
block  (lOSB)  is  a  2-word  array  allocated  in  the  user  program.  It  is 
used  to  receive  the  status  of  a  call  to  an  LPAll-K  support  routine. 
When  a  data  sweep  routine  is  called,  the  lOSB  is  always  the  first  two 
words  of  the  40-word  array  specified  as  the  first  argument  of  the 
call.  The  first  word  of  the  lOSB  contains  the  status  code,  and  the 
second  word  contains  the  buffer  size  in  words. 


• 
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NOTE 


The  2-word  lOSB  is  not  directly  used  by 
the  LPAll-K  driver.  Instead,  the  driver 
uses  a  4-word  lOSB  for  internal 
communications  with  support  routines; 
this  4-word  I0S3  is  completely 
transparent  to  FORTRAN  support  routine 
users.  However,  when  issuing  QIOs,  it 
is  the  4-word  lOSB  that  must  be 
referenced . 


The  first  two  words  of  the  4-word  lOSB 
function  as  a  2-word  overall  lOSB  for 
returning  QIO  completion  status.  The 
driver  returns  status  such  as  sweep 
done,  system  errors,  and  LPAll-K 
hardware  errors  with  this  2-word  portion 
of  the  lOSB. 


• 


The  remaining  two  words  function  as  an 
intermediate  lOSB  for  passing  statue 
information  during  the  data  sweeps. 
MACRO-11  programs  using  QIO  calls  always 
receive  the  correct  2-word  portion  of 
the  lOSB  in  the  AST  generated  by  the 
LPAll-K  driver. 


The  codes  that  can  appear  in  the  first  word  of  an  I/O  status  block  are 

in   ISA-compatible   format   (with   the   exception  of   the  I/O  pending 

condition).   Table  21-3  lists  all   return   codes  except   351;    see 
Section  21. 5) . 


Table  21-3 
Contents  of  First  Word  of  lOSB 


lOSB(l) 

Meaning 

FORTRAN 

MACRO 

0 

1 
301 
302 
303 
304 

305 

lO.PND 

IS. sue 

IE. BAD 
lE.IFC 
lE.DNR 
lE.VER 

lE.ULN 

Operation  pending;   I/O  in  progress 

Successful  completion 

Invalid  arguments 

Invalid  function  code 

Device  not  ready  (See  Section  21.7) 

Unrecoverable   hardware   error    caused    by 
power-fail 

LUN  not  assigned  to  LPAll-K 

(continued  on  next  page) 


21-31 


LABORATORY  PBRIPRBRAL  ACCILIRATOR  DRIVER 


Tabl*  21-3   (Cont.) 
Contents  of  First  Word  of  I08B 


1068(1) 

Meaning 

FORTRAN 

MACRO 

306 
309 
3131 
3151 

31f5 

3171 

320 

323 

359I 

366 

397 

lE.SPC 
IE. DUN 
lE.DAO 
IE. ABO 

lE.PRI 
lE.RSU 
lE.BLK 
IE. NOD 
lE.FHE 
lE.BCC 
lE.IEF 

Illegal  buffer  specification 

Insufficient  UMRs  available  for  request 

Data  overrun 

Request   terminated;    LPAll-K   status   code   in 
I0SB(2) 

Privilege  violation 

Resource  in  use  (load  microcode  only) 

Executive  blr>cked  driver  waiting  for  UMRs 

System  dynamic  memory  exhausted 

Fatal  hardware  error  on  device 

LPAll-K  load  microcode  error 

Invalid  event  flag  specified 

1.  I0SB(2)  contains  an  LPAll-K  status  code.   Refer  to  the   LPAll-K 
User's  Manual  for  explanation  of  status  code. 


21.4   BUFFER  MANAGEMENT 

The  management  of  buffers  for  data  transfers  by  LPAll-K  support 
routines  involves  the  use  of  two  FIFO  (First-In,  First-Out)  queues: 

1.  The  device  queue  (DVQ) 

2.  The  user  queue  (USQ) 

The  device  queue  (DVQ)  contains  the  numbers  of  all  buffers  that  the 
user  task  has  released  to  the  support  routines  in  a  call  to  RLSBUF. 
The  buffers  represented  by  these  numbers  are  ready  to  be  filled  with 
data  (input  sweeps)  or  to  be  emptied  of  data  (output  sweeps).  Any 
buffer  specified  in  a  call  to  INXTBF  must  already  b"  in  DVQ. 

The  user  queue  (USQ)  contains  the  numbers  of  buffers  available  to  the 
user  task.  For  output  sweeps,  this  queue  contains  the  numbers  of 
buffers  that  have  already  been  emptied  by  the  driver.  For  input 
sweeps,  the  buffers  represented  by  USQ  are  those  which  ^re  filled  with 
data.  In  both  instances,  the  user  task  determines  the  next  buffer  to 
use  (that  is,  it  extracts  the  first  element  of  USQ)  by  calling  IGTBUF 
or  IWTBUF. 
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Both  the  DVO  and  USQ  are  initialized  to  -1  —  indicating  no 
buffers  —  when  the  user  task  calls  the  SETIBF  routine.  The  user  task 
must  call  RLSBUF  before  initiating  any  sweep,  since  at  least  one 
buffer  must  be  present  In  DVQ  for  the  first  input  or  output  to  occur. 

For  input  sweeps,  it  is  recommended  that  the  user  task  call  RLSBUF, 
specifying  the  numbers  associated  with  all  the  buffers  to  be  used  in 
the  sweep. 

For  output  sweeps,  the  user  task  can  specify  two  buffers  (for 
continuous  sweeps)  in  the  call  to  RLSBUF.  The  first  action  then  taken 
either  In  a  completion  routine  or  after  a  call  to  IWTBUF  is  to  release 
the  next  buffer.  However,  note  that  this  approach  does  not  represent 
true  multiple  buffering  since  data  overrun  occurs  if  the  second  buffer 
is  not  released  in  time. 

If  a  buffer  overrun  occurs,  the  LPAll-K  normally  aborts  the  affected 
sweep  and  returns  an  appropriate  error  code.  However,  the  option  of 
having  buffer  overruns  treated  as  nonfatal  error  conditions  can  be 
selected  by  specifying  the  appropriate  mode  argument  in  any  of  the 
sweep  calls.  Then,  when  a  buffer  overrun  occurs,  the  LPAll-K 
automatically  defaults  to  buffer  0  for  its  next  data  buffer.  In  this 
case,  the  followip'  special  considerations  regarding  buffer  management 
must  be  observed. 

Call  RLSBUF  before  calling  any  of  the  sweep  control  calls.  However, 
if  buffer  overruns  are  to  be  treated  as  nonfatal  conditions,  the  task 
should  not  specify  buffer  0  in  the  initial  call  to  RLSBUF.  (It  is 
assumed  at  the  outset  that  buffer  0  is  available  for  use  in  this 
manner  and,  therefore,  should  not  be  released.) 

Once  a  buffer  overrun  has  occurred,  buffer  0  is  used  by  the  LPAll-K 
and  placed  on  the  user  queue  just  like  any  other  data  buffer.  At  this 
point,  buffer  0  is  no  longer  available  for  buffer  overruns.  The  task 
then  removes  buffer  0  from  the  user  queue  by  IWTBUF  or  IGTBUF  for 
possible  processing.  It  is  the  task's  responsibility  to  release 
buffer  0  for  future  buffer  overruns  by  specifying  buffer  0  in  a  call 
to  RLSBUF.  Note  that  the  task  cannot  determine  that  buffer  overrun 
occurred  until  it  receives  buffer  0  from  IWTBUF  or  IGTBUF, 

The  LPAll-K  always  uses  buffer  0  following  a  buffer  overrun  if  that 
condition  was  specified  as  nonfatal.  Thus,  when  a  second  buffer 
overrun  occurs  before  buffer  0  has  been  processed  and  made  available 
for  that  purpose,  a  condition  called  "double  buffer  overrun"  occurs. 
In  this  case,  buffer  0  is  not  put  on  the  user  queue  since  the  actual 
contents  of  buffer  0  cannot  be  determined  at  this  time,  and  buffer  0 
may  actually  still  be  on  that  queue.  The  double  buffer  overrun 
condition  is  detected  when  the  task  attempts  to  make  buffer  0 
available  for  future  buffer  overruns  with  the  call  to  RLSBUF.  Note 
that  this  is  the  first  time  that  the  task  is  notified  of  the 
condition.  If  a  double  buffer  overrun  condition  is  detected  during 
the  call  to  RLSBUF,  the  task  must  be  notified  of  tht  condition 
indicating  that  the  previous  processing  of  buffer  0  contents  may  have 
been  of  no  value  (the  LPAll-K  probably  changed  the  buffer's  contents 
while  it  was  being  processed). 
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21.5   LOADING  THE  LPA-11  MICROCODE 

LAINIT  is  a  privileged  task  that  is  used  to  load  all  versions  of 
LPAll-K  microcode.  When  called,  LAINIT  issues  an  10. LCD  function  in  a 
QIO  request,  followed  by  10. INI  and  lO.CLK  function  requests.  The 
lO.CLK  function  starts  the  clock  with  a  default  clock  rate  of  1  MHz. 

During  SYSGEN  Phase  1,  a  command  file  is  generated  with  LPAll-K 
support  selected  through  operator  response  to  SYSGEN  questions. 
During  SYSGEN  Phase  2,  the  command  file  builds  LAINIT  using  additional 
information  obtained  through  operator  response  to  SYSGEN  questions. 
This  information  further  defines  the  LPAll-Ks  system  environment  and 
characteristics  for  the  specific  user  application. 

Separate  tasks  are  built  during  SYSGEN  that  invoke  LAINIT  to  load 
appropriate  LPAll-K  microcode.  These  tasks  are  named  LAINn,  where  n 
corresponds  to  unit  number  (.starting  with  unit  number  0)  for  each 
LPAll-K  unit  in  the  system.  Thus,  LAINIT  is  never  directly  invoked  by 
the  user. 

SYSGEN  automatically  generates  command  lines  in  SYSVMR.CMD  that  will 
install  LAINIT  and  LAINO;  LAIN!  and  subsequent  LPAll-K  unit-numbered 
tasks  are  not  automatically  included  in  the  command  file.  Thus,  the 
user  must  install  these  tasks  (if  they  are  required)  with  VMR  or  MCR. 

Once  LAINIT  and  LAINn  tasks  have  been  installed,  a  particular  version 
of  LPAll-K  microcode  for  a  specific  unit  can  be  loaded  by  running  the 
corresponding  LAINn  task.   For  example: 

>RUN  LAIN2 

executes  LAIN2,  loading  microcode  for  LPAll-K  unit  2. 

When  a  power-fail  recovery  occurs,  the  LPAll-K  driver  terminates  all 
outstanding  activity  and  requests  execution  of  initiating  task(s) 
(LAINn)  for  each  unit.  This  automatically  provides  power-fail 
recovery  for  the  LPAll-K  microprocessor,  provided  the  LAINIT  and  LAINn 
tasks  are  installed.  Note  that  when  either  the  RSX-llM  system  is 
bootstrapped  or  the  LPAH-K  driver  is  loaded,  a  simulated  power-fail 
(resulting  in  driver  power-fail  recovery)  occurs,  loading  microcode 
for  each  LPAll-K  unit.  In  addition,  when  the  LPAll-K  Is  brought 
online  on  an  RSX-llM-PLUS  system,  a  simulated  power-fail  occurs. 

If  the  request  for  the  initiating  task  (LAINn)  fails  or  the  loader 
fails  to  load  the  driver,  the  LPAll-K  unit  does  not  become 
initialized.  Any  further  attempt  to  use  the  LPAll-K  will  fail,  with 
the  device  not  ready  (lE.DNR)  code  returned  to  the  requesting  task. 

If  there  is  no  LPA-llK  present  at  the  default  address,  LAINx  returns 
error  code  351  in  lOSB(l).  This  failure  occurs  if  there  is  more  than 
one  LPA-llK  and  the  one  at  the  default  address  is  removed.  There  must 
always  be  an  LPA-llK  at  the  default  address. 
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All  vcralons  of  LAINn  set  the  real-time  clock  frequency  to  IMHz  by 
default.  The  UCB  device  character  let  lea  trord  4  (U.CW4)  containa  a 
16-bic  buffer  preaet  value  that  controla  the  rate  of  ticka  (that  ia, 
the  rate  ct  which  the  clock  interrupta) .  Thia  value  can  be  aet 
dynamically  or  during  SYSGEN.  The  quotient  reaulting  when  thia  value 
ia  divided  into  1  MHz  ia  the  rate  of  ticka.  For  example,  if  U.CW4 
containa  2,  the  tick  rate  ia  SOOkHZ.  The  uaer  can  iaaue  a  Get  LUN 
Information  syatem  directive  to  examine  the  preaet  value  and  the  MCR 
SET  /BUF  command  can  be  uaed  to  modify  it  while  the  ayatem  is  running. 
This  modification  will  take  effect  the  next  time  the  LPAll-K  is 
reloaded  with  micro-code  by  LAINx. 


Pl.fi   UNLOADING  THE  DRIVER 

In  order  to  attain  maximum  LPAll-K  performance,  the  LPAll-K  driver  la 
designed  to  appear  not  busy  to  the  RSX-1 IM/M-PLUS  Executive.  As  a 
result,  the  potential  problem  exists  that  any  privileged  user  can 
unload  the  driver  while  the  LPAll-K  is  servicing  other  users. 
Therefore,  t:.-  user  must  first  determine  that  the  LPAll-K  is  not  being 
used  prior  to  unloading  the  driver. 


21.7   TIME-OUT  OP  THE  LPAll-K 

The  error  code  lO.DNR  means  that  the  LPAll-R  timed  out  while 
processing  a  user  request.  In  dedicated  mode,  this  condition  can  have 
special  meaning. 

The  LPAll-K  driver  (LADRV)  disables  the  time-out  countdown  following 
LPAll-K  acknowledgement  of  the  user-task  request.  !n  all  cases  in 
multlrequest  mode,  and  in  most  cases  in  dedicated  mode,  this 
acknowledgement  Is  received  almost  immediately  after  the  user-task 
request  is  passed  to  the  LPAll-K.  The  only  caae  when  this  is  not  true 
is  when  the  user  task  requests  that  a  data  sweep  be  started  while  in 
dedicated  mode.  In  this  case,  the  LPAll-K  waits  to  transfer  the  first 
25fi  words  of  data  before  acknowledging  the  sweep  request. 

If  a  task  is  sampling  at  extremely  slow  data  rates  in  dedicated  mode, 
the  time  to  transfer  that  flrat  25fi  words  may  exceed  the  time-out 
count  for  the  device.  Thia  can  be  avoided  by  using  the  m'lltirequest 
mode. 

If  a  task  must  use  dedicated  mode  for  high  sampling  rates,  and  the 
start  of  the  sweep  will  be  delayed  for  an  extended  period  of  time,  the 
time-out  count  for  the  LPAll-K  must  be  disabled.  (Refer  to  the  note 
in  LADRV  describing  this  time-out  problem  and  showing  where  the 
time-out  can  be  safely  disabled  for  sweep  calls.) 

NOTE 

This  procedure  will  disable  the 
detection  of  reel  time-outs  for  sweep 
calls  in  dedicated  mode. 
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21.8   22-BIT  ADDRESSING  SUPPORT 

The  LPAll-K  driver  supports  22-bit  addressing  on  systems  ^avi^g  that 
capability.  When  the  system  employs  22-bit  addressing,  certain 
restrictions  are  imposed.  As  a  result,  tasks  written  for  use  with 
earlier  LPAll-K  driver  versions  may  not  run  without  user  task 
modifications.  These  restrictions  are  discuiised  in  the  remainder  of 
this  sectioi.. 

When  the  LPAll-K  driver  is  executed  on  22-bit  systems,  a  certain 
contiguity  of  user-task  data  structures  must  be  established.  The  task 
data  transfer  buffers  and  the  IBUF  array  must  be  contiguous.  In 
addition,  the  task  random  channel  list  (if  present)  and  the  last  data 
transfer  buffer  must  be  contiguo>is.  Thus,  the  correct  sequence  for 
us9r-task  data  is  the  IBUF  array,  followed  by  the  task  data  transfer 
buffers,  followed  by  the  task  random  channel  list.  Failure  to 
structure  the  user-task  data  in  this  i,;anner  can  result  in  illegal 
buffer  specification  errors  (lE.SPC)  biding  re..urned  or  possible 
corruption  of  task  address  space  by  data  sweeps. 

Since  the  LPAll-K  user  task  can  potentially  request  more  buffer  space 
than  there  is  UMR  mapping  space,  a  limit  on  the  total  number  of  UMRs 
that  can  be  used  by  the  LPAll-K  driver  at  any  time  must  be  specified. 
This  limit  is  specified  during  SYSGEN  part  1,  along  with  the  Interrupt 
vector  ap J  CSR  address  for  the  LPAll-K. 

If  a  task's  UMR  requirements  will  cause  the  total  number  of  UMRs 
currently  in  use  by  the  LPAll-K  to  exceed  the  SYSGEN-speclf led  limit, 
the  task  will  receive  an  Insufficient  UMRs  Available  For  Request 
(IE. DUN)  error  code  in  lOSB(l)  of  the  IBUF  array. 

This  condition  can  be  avoided  by  setting  the  UMR  limit  to  the  expected 
minimum  number  required  for  smooth  LPAll-K  operation  for  all  expected 
users.  Since  each  UMR  maps  8K  bytes,  each  user's  requirements  can  be 
calculated  as  follows: 

•  Each  IBUF  array  requires  76(10)  bytes  of  UMR  mapping. 

e  Add  this  result  tr>  the  byte  length  of  all  the  contiguous 
transfer  buffers  to  be  used  In  the  sweep. 

•  Add  this  result  to  the  byte  length  of  the  random  channel  list 
(if  It  exists) . 

•  The  number  of  UMRs  the  user  task  needs  is  the  total  byte  count 
divided  by  8192  (8K)  and  rounded  up  to  the  next  8K  (if  not  an 
exact  multiple  of  8192). 

Because  there  are  only  31  UMRs  available  for  the  entire  system,  it  Is 
not  desirable  to  allow  the  LPAll-K  driver  (through  the 
SYSGEN-speclf led  limit)  to  have  access  to  all  or  nearly  all  UMRs  at 
any  given  time.  Since  other  device  drivers  may  also  require  UMR 
mapping,  the  total  allocation  of  UMRs  by  LADRV  can  slowly  choke  a 
system,  and  for  that  reascn  allocation  of  UMRs  must  oe  carefully 
considered . 
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Th«  UMR  allocation  limit  for  the  LPAll-K  can  be  changed  by  directly 
modifying  the  value  in  the  LPAll-K's  UCB  word  U.LAUB;  it  is  not 
necessary  to  do  another  SYSGEN.  Use  the  OPEN  command  to  access  and 
hange  the  limit  to  the  new  value.  Possible  values  can  range  from 
'0-31.  Then,  make  the  required  change,  UNLOAD,  and  then  LOAD  the 
LPAll-K  driver.  If  the  LPAll-K  driver  is  resident,  the  value  in 
U.LAUB-f?  must  also  be  changed  to  the  new  value. 

NOTE 

Be   sure   the   LPAll-K   is   idle  before 
attempting  to  access  the  UCB, 

It  is  possible  for  a  condition  to  exist  where  there  may  not  be  enough 
UMRs  available  for  the  Executive  to  allocate  to  the  driver  at  the  time 
the  request  is  made,  even  if  the  number  of  UMRs  necessary  to  map  the 
user  task's  request  are  within  the  SYSGEN-def ined  limit.  When  this 
happens,  the  Executive  blocks  the  driver  until  Its  UMR  request  can  be 
granted.  Since  this  condition  can  introduce  sweep  timing  errors,  the 
current  sweep  is  unconditionally  aborted  and  an  appropriate  error  code 
(lE.BLK)  is  returned  to  the  task  in  lOSB(l). 


21.9   SAMPLE  PROGRAMS 

C        LPAll-K  SAMPLE  PROGRAM 

C 

C  SAMPLE  SHOWS  THE  BASIC  FLOW  FOR  PROGRAMMING  THE  LPAll-K  IN  A  HIGHER 

C  LEVEL  LANGUAGE.   IT  IS  EXPECTED  THE  USER  WILL  TEST  lOSB  RETURNS  AND 

C  ERROR  INDICATORS  (IND)  AS  NECESSARY.   SYNCHRONOUS  PROGRAM  TERMINATION 

C  IS  SUGGESTED.  NOTE:  THIS  SAMPLE  PROGRAM  WILL  NOT  EXECUTE  CORRECTLY  IN 

C  22-BIT  MODE 

C 

C        D/A  DEDICATED  MODE  WITH  CONTINUOUS  SAMPLING 

C 

C        PROGRAM  RUNS  3  LOOPS  (BASED  ON  NCNT) .   ON  FIRST  LOOP, 

C        STOPS  SYNCHRONOUSLY  AT  END  OF  PRESENT  BUFFER  WHICH  HAPPENS 

C        TO  BE  BUFFER  #1  BEING  FILLED  FOR  THE  2ND  TIME. 

C        THE  2ND  LOOP  TERMINATES  ASYNCHRONOUSLY  (IWHEN=0). 

C        THE  3RD  LOOP  TERMINATES  ASYNCHRONOUSLY  ALSO. 

C 

C 

DIMENSION  IBUF(40) ,I0SB(2) ,NB(1024,8) 

EQUIVALENCE  ( IBUF ( 1 ) , lOSB ( 1 ) ) 

EQUIVALENCE  (NO , NB ( 1 , 1 ) ) , (Nl , NB (1 , 2) ) , {N2 , NB (1 , 3) ) , (N3 , NB ( 1 , 4 ) ) 

EQUIVALENCE  (N4 ,NB ( 1 , 5) ) , (N5 , NB ( 1 , 6) ) , (N6 , NB ( 1 , 7) ) , (N7 ,NB ( 1 , 8) ) 

CALL  CLOCKA  (4,-1) 

IWHEN=1 

NCNT=0 
2        ICNT=1 

5    CALL  SETIBF(IBUF,IND, ,N0,N1 ,N2,N3) 
C 

C  INITIALIZE  BUFFERS  TO  ALL  -2'S 
C 

DO  10  J-1,8 

DO  10  K=l,1024 
10    NB(K,J)=-2 

CALL  RLSBUF(IBUF,IND,1,2,3) 

CALL  DASWP(IBUF,1024, , , ,20) 
20       CALL  IWTBUF(IBUF,20,IBUFNO) 

CALL  RLSaUF  ( IBUF, IND, IBUFNO) 

WRITE  (1,300)  IBUFNO,IOSB(i) ,I0EB(2) ,ICNT 

IF  (NCNT.EQ.3)  GOTO  40 
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IP  (ICNT.EQ.fi)  GOTO  2 

ICNT-ICNT+1 

IP  (ICNT.NE.4)  GOTO  20 

CALL  STPSWP  (IBUF,IBUFNO) 

IWHEN-0 

NCNT-NCNT+1 

GOTO  20 
40       CALL  IGTBUF(IBUF,IBUFNO) 

WRITE  (1,300)  IBUFN0,I0SB;1) ,I0SB(2) ,ICNT 
300      FORMAT  (3X, I 10, 208 , 110) 

STOP 

END 

The  following  sample  program  will  test  the  digital   I/O   interface  of 
the  LPAll-K.   It  will  execute  correctly  in  22-bit  mode. 

C 

C  PROGRAM  TO  TEST  DIGITAL  INPUT  AND  OUTPUT  FOR  LPAll-K 

C  DIGITAL  EQUIPMENT  CORPORATION 

C 

C  IHIS  PIIOGRAM  rs  DESIGNED  TO  OUTPUT  A  DATA  BUFFER  TO  THE  LPAll-K 

C  DIGITAL  i/O  INTERFACE  AND  AT  THE  SAME  INSTANT  FOR  EACH  SAMPLE 

C  WORD  READ  THhl  HLS'JLTS  BACK.  THE  DATA  BUFFERS  ARE  COMPARED  TO 

C  MAKE  SURE  THE  TRANSFER  IS  COMPLETED  SUCCESSFULLY. 

C 

Q      *•*•♦•  NOTE!  ****** 

C        THIS  PROGRAM  WILL  WORK  IV    AND  ONLY  IF  THE  DIGITAL  I/O 

MODULE 

C        UNIT  SPECIFIED  HAS  THE  MAINTENANCE  JUMPER  "WRAP-AROUND" 

CABLE 

C        INSTALLED  I  1 ! I 

c 

C 

C  RESERVE  STORAGE  FOR  LPAll-K  ROUTINES 

C 

C        THIS  PROGRAM  WILL  WORK  IN  22-BIT  MODE 

e 

C  DATA  BUFFERS 
C 

INTEGER*2  iBUFI(40) , INBUF ( 300, 4) 

INTEGER*2  COMMI(1240) 

EQUIVALENCE (IBUFI (1 ) ,C0MMI(1) ) 

EQUIVALENCE(INBUF(1,1) ,COMMI (41) ) 

INTEGER*2  IBUFO (40) ,OUTBUF ( 300 , 4) 
INTEGER*2  COMMO(1240) 
EQUIVALENCE ( IBUFO (1) ,C0MM0(1) ) 
EQUIVALENCE (OUTBUF{ 1,1) ,C0MM0(41) ) 

C  RESERVE  STORAGE  AND  EQUIVALENCE  FOR  RSX  I/O  STATUS  BLOCKS 
L0GICAL*1  INI0S(4) ,0UTI0S(4) 
EQUIVALENCE  (IBUFOd  )  ,OUTIOS  (1 )  )  ,  ( IBUFI  (1 )  ,  INIOS  (1 )  ) 

e 

C  SET  BUFFER  SIZE  TO  USE  FOR  THIS  REQUEST  -  MAXIMUM  OF  300 

WITHOUT 

C  CHANGING  THE  DIMENSION  STATEMENTS.  MUST  BE  EVEN! 

ISIZE=300 
€ 
C    INITIALIZE  THE  PASS  COUNTER  FOR  THE  LOOP 

IPASS=1 
C 
C  SET  LPAll-K  LOGICAL  UNIT  NUMBER  AND  ASSIGN  IT  TO  LAO: 

ILUN»7 

CALL  ASSIGN(ILUN,'LA: ' ,0,ISTAT) 

IFiISTAT  .LT.  0)GO  TO  100 
C 
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C  INITIALIZE  THE  OUTPUT  DATA  BUFFER 

DO  2  J-1,4 

DO  2  I-1,ISIZE,2 

OUTBUF(I,J)-"125252 

0UTBUF(I+1, J) -"052525 
2        CONTINUE 
C 

C  STOP  LPAll-K  REAL  TIME  CLOCK  "A"  THIS  WILL  MAKE  SURE  THAT 
C  NOTHING  HAPPENS  WHEN  WE  INITIALIZE  THE  TWO  SWEEPS. 
5        CALL  CLOCKA(0,0,ISTAT,ILUN) 

IFdSTAT  .NE.  1)G0  TO  110 
C 

C  INITIALIZE  THE  INPUT  DATA  BUFFER.  ASSUME  THE  LPAll-K  DIGITAL 
C  I/O  INTERFACE  IS  CONFIGURED  IN  THE  DATA  LATCH  MODE  (AS  OPPOSED 
C  TO  SENSE).  THUS  THE  OUTPUT  DATA  BUFFER  MUST  CONTAIN  A  BIT 
CHANGE 
C  FOR  EVERY  BIT  POSITION  IN  SUCCEEDING  DATA  WORDS. 

DO  10  J-1,4 

DO  10  I-1,ISIZE 

INBUP(I,J)-0 
10       CONTINUE 
C 

C  INITIALIZE  DIGITAL  OUTPUT  SWEEP.   THIS  MUST  BE  DONE  BEFORE  INIT 
C  OF  DIGITAL  INPUT  SWEEPl  THE  LPAll-K  PROCESSES  THE  TRANSFER  OF 
C  DATA  IN  THE  ORDER  OF  THE  SPECIFICATION  OF  THE  SWEEPS.   THUS  WE 
C  WANT  TO  OUTPUT  BEFORE  WE  INPUT. 

CALL 
SETIBF(IBUFO,ISTAT, ,0UTBUF(1,1) ,0UTBUF(1,2) ,0UTBUF(1,3)  , 

1    0UTBUF(1,4)) 

IFdSTAT  .NE.  1)G0  TO  120 
C 

C  RELEASE  BUFFER  FOR  OUTPUT  SWEEP 
C  ALL  FOUR  BUFFERS  —  INDEXES  0,1,2,3  —  ARE  RELEASED 

CALL  RLSBUF(IBUFO,ISTAT,0,l,2,3) 

IFdSTAT  .NE.  1)G0  TO  130 
C 

C  "START"  DIGITAL  OUTPUT  SWEEP.  REMEMBER  NOTHING  WILL  HAPPEN 
UNTIL 

C  WE  START  THE  REAL  TIME  CLOCK.  THE  LPAll-K  WILL  PROCESS  THE 
REQUEST 

C  AND  BE  ALREADY  TO  TRANSFER  DATA  WHEN  WE  RESUME  THE  CLOCK. 
C  EVENT  FLAG  14  IS  SPECIFIED.  A  DIFFERENT  EVENT  FLAG  MUST  BE 
C  SPECIFIED  FOR  THE  DIGITAL  INPUT  SWEEP  SO  THE  FORTRAN  PROGRAM 
C  CAN  SYNCHRONIZE  WITH  TWO  INDEPENDENT,  ASYNCHRONOUS  PROCESSES. 

CALL  DOSWP(IBUFO,ISIZE,4,0,1,14,30,0) 
C 
C 

C  NOW  INITIALIZE  FOR  DIGITAL  INPUT  SWEEP.   THE  SAMPLING 
PARAMETERS 

C  MUST  BE  THE  SAME  FOR  BOTH  THE  INPUT  AND  OUTPUT  SWEEP.   WE  WANT 
C  TO  WRITE  AND  READ  THE  SAME  DATA  WORD  AT  THE  SAME  TIME. 

CALL 
SETIBFdBUFI,ISTAT,,INBUF(l,l)  ,INBUF(1,2)  ,INBUF{1,3)  , 

1    INBUF(1,4)) 

IFdSTAT  .NE.  1)G0  TO  140 
C 
C  RELEASE  THE  INPUT  BUFFERS 

CALL  RLSBUF(IBUFI,ISTAT,0,1,2,3) 

IFdSTAT  .NE.  1)G0  TO  150 
C 

C  "START  DIGITAL  OUTPUT  SWEEP.  AGAIN,  NOTHING  WILL  HAPPEN  UNTIL 
C  WE  RESUME  THE  LPAll-K  REAL  TIME  CLOCK. 

C  EVENT  FLAG  15  IS  SPECIFIED  TO  SEPARATE  THE  INPUT  AND  OUTPUT 
SWEEPS. 

CALL  DISWP(IBUFI,ISIZE,4,0,1,15,30,0) 
C 
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C  NOW  FOR  THE  BIG  EVENTI  WE  START  THE  CLOCK  AND  SEE  WHAT  HAPPENS. 

CALL  CLOCKA(1,-150,ISTAT,ILUN) 

IFdSTAT  .NE.  1)G0  TO  150 
C 

c 

C  THE  LPAll-K  SHOULD  NOW  BEGIN  TO  TRANSFER  DATA 

C  FIRST  WE  WAIT  FOR  THE  DIGITAL  OUTPUT  SWEEP  TO  FINISH.   IT  WAS 

C  STARTED  FIRST  AND  SHOULD  FINISH  FIRST.   WE  VERIFY  THAT  IT 

C  FINISHES  CORRECTLY  OR  CHECK  FOR  ERRORS. 

IS       CALL  IWTBUF(IBUF0,14,IBUFN0) 

C 

C  IF  BUFFER  NUMBER  IS  -1,  THEN  ERROR 

C  IF  BUFFER  NUMBER  IS  0,1,  OR  2,  THEN  CONTINUE 

C  IF  BUFFER  NUMBER  IS  3,  THEN  FINISHED 

IF(IBUFNO  .LT.  0)  GO  TO  160 
C 

C  NOW  WAIT  FOR  THE  DIGITAL  INPUT  SWEEP  TO  FINISH.   THE  SAME  ERROR 
C  CONDITIONS  APPLY. 

CALL  IWTBUF(IBUFI,15,IBUFN0) 

IFdBUFNO  .LT.  0)GO  TO  170 

IFdBUFNO  .LE.  2)G0  TO  15 
C 

C  THE  FACT  THAT  WE  HAVE  GOTTEN  HERE  SAYS  THE  LPAll-K  HAS  DONE  ITS 
C  THING. 
C  CHECK  THE  INPUT  DATA  BUFFERS  AGAINST  THE  OUTPUT  DATA  BUFFERS 

DO  20  J-1,4 

DO  20  I-1,ISIZE 

IF(INBUF(I,J)  .NE.  OUTBUF(I,J) )G0  TO  180 
to       CONTINUE 
C 

C  SUCCESSFUL  COMPLETION,  LET  EVERYONE  KNOW.  THEN  GO  BACK  A*">  DO 
IT 
C  AGAIN. 

WRITE(5,1000) IPASS 
1000     FORMATC   REQUEST  COMPLETEI ',  2X,  16) 

IPASS-IPASS+1 

GO  TO  5 
C 

C  REPORT  ANY  ERRORS  THAT  HAVE  BEEN  UNCOVERED  IN  THE  EXAMPLE. 
C 

100      WRITE(5,1010)ISTAT 
1010     FORMAT(//,'  ERROR  ASSIGNING  LUN  TO  LPAll-K    ',16) 

CALL  EXIT 
110      WRITE(5,1020) ISTAT 
1020     FORMAT(//,'  ERROR  STOPPING  LPAll-K  CLOCKA     ',16) 

CALL  EXIT 
120      WRITE(5, 1030) ISTAT 
1030     FORMAT (//,'  ERROR  FROM  SETIBF  -  OUTPUT  BUFFER    ',16) 

CALL  EXIT 
130      WRITE(5, 1040) ISTAT 
1040     FORMAT(//,'  ERROR  FROM  RLSBUF  -  OUTPUT  BUFFER    ',16) 

CALL  EXIT 
140      WRITE(5, 1050) ISTAT 
1050     FORMAT(//,'  ERROR  FROM  SETIBF  -  INPUT  BUFFER    ',16) 

CALL  EXIT 
150      WRITE(5, 1060) ISTAT 
1060     FORMAT(//,'  ERROR  FROM  RLSBUF  -  INPUT  BUFFER    ',16) 

CALL  EXIT 
160      WRITE(5,1070)IBUFNO, (OUTIOS(I) ,1=1,4) 
1070     FORMAT(//,'  ERROR  FROM  DOSWP    ' , 12, 4 (3X,04) ) 
C 

C  ***  WARNING  ***  DISWP  MIGHT  STILL  BE  ACTIVE  WHEN  YOU  EXIT 
C 

CALL  EXIT 
170      WRITE(5,1080)IBUFNO,  (INIOSd)  ,1=1,4) 
1080     FORMAT(//,'  ERROR  FROM  DISWP    ' , 12, 4 ( 3X,04) ) 
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C 

C  •*•  WARNING  •**  DOSWP  MIGHT  STILL  BE  ACTIVE  WHEN  YOU  EXIT 
C 

CALL  EXIT 
180      WRITE(5,1090)I,J,OUTBUP(I,J) ,INBUF(I,J) 
1090     FORMAT(//,'  •DATA  ERROR*  -  WORD  |  ',14, 2X, 14, 4X,06, 2X,06) 

CALL  EXIT 

END 
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CHAPTER  22 
K-SZRICS  PERIPHKRAL  SUPPORT  ROUTINES 


22.1   INTRODUCTION 

K-saries  laboratory  p.frlpheral  modulss  are  supported  through  a  set  of 
program-callable  routines  that  are  linked  with  the  user's  task  at 
task-build  time.  These  routines  are  highly  modular.  Therefore,  a 
particular  task  contains  only  that  code  necessary  for  the  facilities 
actually  used.  Additionally,  the  support  routines  perform  input  and 
output  operations  through  the  Connect  to  Interrupt  Vector  (CINT$) 
Executive  directive.  This  directive  allows  the  user's  task  to  bypass 
normal  QIC  processing  and  perform  I/O  almost  completely  independent  of 
the  Executive. 

The  following  subsections  briefly  describe  the  K-series  laboratory 
periraerals,  the  features  provided  by  the  K-series  support  routines, 
and  .he  generation  and  use  of  these  routines. 


22.1.1  K-8«ri«B  Laboratory  Paripharals 

The   K-series  peripheral   support    routines   provide   single-user, 
task-level  support  for  the  following  laboratory  peripheral  modules: 

•  AAll-K  D/A  converter 

•  ADll-K  A/D  converter 

•  AMll-K  multiple  gain  multiplexer 

•  DRll-K  digital  I/O  interface 

•  KWll-K  dual  programmable  real-time  clock 

•  AAVll-A  D/A  converter  (LSI-11-bus-compatible) 

•  ADVll-A  A/D  converter  (LSI-11-bus-compatible) 

•  DRVll  parallel  line  unit  (LSi-ii-bus-compatible) 

•  KWVll-A  programmable  real-time  clock  (LSI-1 1-bus-compatible) 
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The  maximum  supported  hardware  configuration  consists  of  one  KWll-K 
and  sixteen  of  each  of  the  AAll-K,  AOll-K  (with  optional  AMll-K),  and 
DRll-K  modules.  The  minimum  conf igurat ion«  if  synchronous  sweeps  are 
desired,  would  be  one  KWll-K  and  any  one  of  the  three  other  modules. 
A  single  DRll-K  supports  nonclocked,  interrupt-dr iven  I/O  sweeps  oe 
single  digital  input  or  output.  A  single  ADll-K  supports  single-word 
A/D  input  and  nonclocked,  overflow-driven  sampling  (provided  that  the 
A/D  conversion  is  started  with  the  EXT  start  input  on  the  ADll-K).  An 
AAll-K  supports  burst  mode  output  and  scope  control. 


22.1.1.1  AAll-K  D/A  Converter  -  The  AAll-K  includes  four  12-bit 
digital-to-analog  converters  (DACs)  and  an  associated  disolay  control. 
The  display  control  permits  the  user  to  display  data  in  the  form  of  a 
4096  X  4096  dot  array.  Under  program  control,  a  dot  may  be  produced 
at  any  point  in  thin  array,  and  a  series  of  these  dots  may  be 
programmed  sequentially  to  produce  graphical  output.  The  display 
control  may  output  to  chart  or  X/Y  recorder  or  CRT  display  unit. 

The  AAVll-A  is  an  LSI-1 1-bus-compatible  D/A  converter  with 
characteristics  similar  to  those  of  the  AAll-K. 


22.1.1.2  ADll-K  A/D  Converter  -  The  ADll-K  is  i  12-bit  successive 
approximation  converter  that  enables  the  user  to  trample  analog  data  at 
specified  rates  and  to  store  the  equivalent  digital  value  for 
subsequent  processing.  The  basic  subsystem  consists  of  an  input 
multiplexer  (switch-selectable  between  16-channel  single-ended  or 
8-channel  differential),  sample-and-hold  circuitry,  and  a  12-bit  A/D 
converter.  By  changing  jumpers,  the  analog  inputs  can  be  made  bipolar 
or  unipolar. 

The  ADVll-A  is  an  LSI-11-bus-compatible  D/A  converter  with 
characteristics  similar  to  those  of  the  ADll-K. 


22.1.1.3  AMll-K  Multiple  Gain  Multiplexer  -  The  AMll-K  is  a 
multiplexer  expander  th6t  supplements  the  16-channel  single-ended  (8 
differential)  analog  input  multiplexer  in  the  ADll-K.  The  expansion 
is  done  in  three  independent  groups  on  the  AMll-K.  Each  group  can  be 
set  to  16  single-ended  or  pseudo-differential  or  8  differential  input 
channels;  oach  group  can  have  a  gain  of  1,  4,  16,  or  64  assigned  to 
it  by  a  switch  in  the  amplifier. 


22.1.1.4  DRll-K  Digital  I/O  Interface  -  The  DRll-K  is  a 
general-purpose  digital  input/output  interface  capable  of  the  parallel 
transfer  of  up  to  16  bits  of  data,  under  program  control,  between  a 
PDP-11  UNIBUS  computer  and  an  external  device  (or  another  DRll-K). 

The  DRVll  is  an  LSI-ll-bus-compatible,  general-purpose  input/output 
interface  with  characteristics  similar  to  those  of  the  DRll-K. 
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22.1.1.5  RNll-K  Dual  PrograMiabl*  Raal-Tla*  Clock  -  The  KWll-K  is  a 
dual  progrannable  raal-tina  clock  option  usad  in  PDP-11  UNIBUS 
computars.   Paaturas  include: 

Clock  A 

•  16-bit  counter 

a  Ifi-bit  programmable  preaet/buf far  register 

a  Pour  modes  of  operation 

a  Two  external  inputs  (Schmitt  triggers) 

a  Bight  clock  rates,  program  selectable 

a  Five  clock  frequencies,  crystal  controlled  for  accuracy 

a  Processor  actions  synchronized  to  external  events 

Clock  B 

e  8-bit  counter 

a  8-bit  programmable  preset  register 

a  Repeated  interval  mode  of  operation 

a  One  external  input  (Schmitt  trigger) 

e  Seven  clock  rates,  program  selectable 

a  Five  clock  frequencies,  crystal  controlled  for  accuracy 

The  KWVll-A  is  an  LSI-11-bus-compatible  real-time  clock  with 
characteristics  similar  to  those  of  the  KWll-K. 

22.1.2   Support  Routine  Features 

The  RSX-llM  program-callable  K-series  support  routines  provide  the 
following  features: 

a  Clock  ov'siflow  or  trigger-driven  A/D  sweep 

a  Clock  overflow  or  interrupt-dr iven  digital  input  sweep 

a  Clock  overflow  or  interrupt  driven  digital  output  sweep 

a  Clock  overflow  or  burst  mode  D/A  sweep 

a  Single  digital  input 

a  Single  digital  output 

a  Single  A/D  input 
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•  Scop*  control 

•  Histogram  sampling 

•  Schmitt  Trigger  simulation 

•  Clock  control 

V  16-bit  software  clock 

•  A/D  input  to  real  number  conversion 

•  Buffer  control 

Immediate  digital  input  or  output  can  be  performed  at  any  time. 
Multiple  clock-driven  sweeps  can  be  Initiated  if  this  optional  feature 
was  selected  during  the  K-series  generation  dialog  (see  Section 
22.1.3.1).  Such  sweeps,  however,  are  subject  to  the  following 
restrictions: 

1.  Regardless  of  the  number  of  controllers  present,  there  can  be 
only  one  active  A/D  sweep  at  any  point  in  time.  The  same 
restriction  holds  true  for  D/A  sweeps.  It  is  possible, 
however,  to  perform  digital  Input  and  digital  output  sweeps 
simultaneously,  using  the  same  DRll-K,  so  long  as  this 
feature  is  selected  during  the  generation  dialog. 

2.  There  can  be  no  conflict  in  clock  rates  among  the  sweeps. 

3.  Only  the  first  sweep  can  use  the  delay  from  start  event. 

4.  The  interevent  time  data-gathering  routine  cannot  run  in 
parallel  with  any  other  clock-driven  sweeps. 


22.1.3  Generation  and  Use  of  K-Series  Routines 

To  use  K-series  support  routines,  the  user  must  do  the  following  three 
things  during  SYSGEN: 

•  Reserve  necessary  vector  space. 

•  Specify  that  the  CINT$  Executive  directive  is  to  be   included 
in  the  system. 

•  Specify  that  AST  support  is  required. 

At  a  point  in  time  subsequent  to  SYSGEN,  the  user   follows  particular 
procedures  for  the  following: 

1.  Generation  of  K-series  r;upport  routines 

2.  Program  use  of  K-series  routines 

These  two  procedures  are  detailed  in  the  following  subsections. 
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22.1.3.1  Generation  of  R-s«rl*a  Support  Routines  -  An  indirect  com- 
mand file,  similar  to  those  used  for  SYSGEN  itself,  is  used  to 
generate  the  K-series  support  routine  library  and  other  necessary 
facilities.   This  command  file  Is  Invoked  by  typing  the  following: 

>9[200,200]SGNKLAB 

The  dialog  initiated  by  this  command  determines  the  device 
configuration  of  the  subsystem,  the  maximum  number  of  buffers  that 
will  be  used  on  a  per-sweep  basis,  and  the  inclusion  or  omission  of 
optional  features  such  as  multiple  clock-driven  sweeps  and  duplex 
digital  I/O  sweeps. 

After  this  Information  has  been  obtained,  the  command  file  creates  the 
following : 

1.  A  prefix  file,  f 45, lOlKPRB.MAC,  for  use  drrlng  assembly  of 
K-series  support  routines. 

2.  A  data  base  file,  f 45, 10] KIODT.MAC,  containing  control  blocks 
needed  to  support  the  devices. 

3.  A  common  block  file,  [45, 101KCOM.MAC,  that  allows  user  tasks 
to  access  the  I/O  page.  This  file  is  used  only  on  mapped 
systems. 

4.  On  mapped  systems  only,  two  indirect  command  files: 

a.  (45, 741KCOMBLD.CMD,  which  is  a  TKB   build   file   for   the 
common  block 

b.  [1,54] INSKCOM.CMD  that  is   used   to   install   the   common 
block 

At  the  user's  option,  the  K-serles  routines  themselves  can  then  be 
assembled  and  an  object  library  created.  The  user  can  specify  the 
naue  of  this  library  or  accept  the  following  default  file 
specification : 

LB: [1,11KLABLIB.0LB 


22.1.3.2   Program  Use  of  K-serles  Routines  -  The   steps   required   for 
routine  program  use  of  K-series  support  routines  are  as  follows: 

1.  Compile  or  assemble  the  program.  If  the  task  will  be 
overlaid,  it  is  required  that  both  the  buffers  used  by  the 
K-series  support  routines  and  the  support  routines  themselves 
reside  In  the  root  section  of  the  overlay  structure. 
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2.   Invok*  TKBt 

a.  On  mapped  ayatana  only,  uaa  tha  /PRiO  awitch  to   indicata 
that  tha  taak  ia  privilaqad. 

b.  Include  tha   following   indirect   comaand   among   tha 
reaponaea  to  tha  TKB  prompt: 

TKB>« ( 1 , 5x] LNK2KLAB 

where  x  ia  0   for   unmapped   ayatama  and   4  for  mapped 
ayatama. 

c.  On  mapped  ayatama  only,   enter   the   following   indirect 
command  in  reaponae  to  the  prompt  for  optiona: 

ENTER  OPTIONS 
9(l,54]LNK2KCOM 


// 

3.   On  mapped  systems  only,  enter  the  following  indirect  command 
from  a  privileged  terminal  before  executing  the  program: 

>9[l,54]INSKCOM 

The  following  ia  a  complete  example  of  the  atepa  previously  deacribed: 

>P4P  KTEST,KTEST/-SP-KTEST 

>TKB 

TKB>KTEST/PR:0,KTEST/-SP-KTEST, [ 1 , 1 1 P4P0TS/LB 

TKB>9[1,54]LNK2KLAB 

TKB>/ 

ENTER  OPTIONS 

TKB>(^(l,54]LNK2KCOM 


TBK>// 


22.2   THE  PROGRAM  INTBRPACB 

A  collection  of  program-callable  subroutines  providea  accaas  to  tha 
K-series  laboratory  peripherals.  The  formata  of  (-hese  calls  are  fully 
documented  here  for  FORTRAN  programs.  MACRO-11  programmers  access 
these  same  subroutines  either  through  the  standard  subroutine  linkage 
or  through  the  use  of  two  special-purpose  macros.  Both  techniques  are 
described  in  Section  22.2.2.  Both  FORTRAN  and  MACRO  programs  must 
contain  at  least  one  I/O  Status  Block  (lOSB),  deacribed  in  Section 
22.2.3,  for  retrieval  of  status  information. 
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22.2.1  rORTRAM  Intarfac* 

Table  22-1  list*   th«   FORTRAN   interface 
K-serias  laboratory  ptripharals. 


subroutines   Cor   accessing 


Table  22-1 
FORTRAN  Subroutines  Cor  K-serieu  Laboratory  Peripherals 


Subroutine 

Function 

ADINP 

Initiate  single  analog  input 

ADSWP 

Initiate  synchronous  A/D  sweep 

CLOCKA 

Set  Clock  A  rate 

CLOCKS 

Control  Clock  B 

CVADF 

Convert  A/D  input  to  floating  point 

DASWP 

Initiate  synchronous  D/A  sweep 

DIGO 

Digital  start  event 

DINP 

Digital  input 

DISWP 

Initiate  synchronous  digital  input  sweep 

DOSWP 

Initiate  synchronous  digital  output  sweep 

DOUT 

Digital  output 

FLT16 

Convert  unsigned  integer  to  a  real  constant 

GTHIST 

Gather  interevent  time  data 

IBFSTS 

Get  buffer  status 

ICLOKB 

Read  16-bit  clock 

IGTBUF 

Return  buffer  number 

INXTBF 

Set  next  buffer 

IWTBUF 

Wait  for  buffer 

RCLOKB 

Read  16-bit  clock 

RLSBUF 

Release  data  buffer 

RMVBUF 

R;>move  buffer  from  device  queue 

SCOPE 

Control  scope 

SETADC 

Set  channel  information 

SETIBF 

Set  array  for  buffered  sweep 

STPSWP 

Stop  sweep 

XRATE 

Compute  clock  rate  and  preset 
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Th«  calling  sequences  of  the  routines  listed  In  Table  22-1  are 
compatible  with  the  routines  for  the  LPA-11,  described  in  Chapter  21. 
The  following  subsections  briefly  describe  the  function  and  format  of 
each  FORTRAN  sjbroutine  call. 


22.2.1.1   ADINP:  Initiate  Single  Analog  Input  -  The   ADINP    routine 
obtains  a  single  word  as  input  from  the  A/D  converter. 

ADINP  can  be  invoked  as  a  subroutine  or  a  function  as  follows: 

CALL  ADINP  ([iflag] ,[ichan] ,ival) 

or 

ival-IADINP  ( [iflag] , tichan] , [ival] ) 

Iflaq      '  ' 

The  gain  options: 

0  Absolute  channel  addressing  (default).  This  is  the  only 
mode  supported  on  the  ADVll  (0-bus) . 

1  Sample  at  a  gain  of  1.  In  modes  1,  2,  3,  4,  and  5  each 
ADll-K/AMll-K  is  treated  as  16  channels  with  channels 
17-63  strapped  to  gains  4,  16,  and  64.  The  48 
multiplexer  channels  are  selected  by  the  software 
according  to  the  gain  specification.  Mode  values  1,  2, 
3,  4,  and  5  are  not  supported  on  the  ADVll  (Q-bus 
version) . 

2  Sample  at  a  gain  of  4.  , 

3  Sample  at  a  gain  of  16. 

4  Sample  at  a  gain  of  64. 

5  Perform  auto  gain  ranging. 

Ichan 

Selects  Lhe  channel  to  be  sampled.   The  default  is  0. 


Ival 


Receives  the  sample.   The  gain  bits  will  be  inserted  if  iflag   is 
nonzero. 


22.2.1.2  ADSWP:  Initiate  Synchronous  A/D  Sweep  -  The  ADSWP  routine 
initiates  a  synchronous  A/D  input  sweep  through  an  ADll-K  (and,  if 
present,  the  AMll-K).  The  analog  input  word  placed  in  the  user  buffer 
consists  of  the  12  bits  read  from  the  A/D  converter  and  (except  when 
the  mode  parameter  equals  0)  the  2  gain  bits  read  from  the  A/D  status 
register.  A  value  of  177776(8)  is  returned  for  A/D  time-out.  A  value 
of  177777(8)  is  returned  on  an  A/D  conversion  error.  Such  errors  are 
typically  caused  by  conversions  occurring  too  fast. 
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If  differential  input  is  desired,  the  channel  increment  must  be  set  to 
2  by  calling  the  SETADC  routine.  The  default  channel  increment  is  1 
(single-ended  input) . 

NOTE 

This  routine  will  expect  to  have  the  STl 
OUT  from  the  KWll-K  or  similar  trigger 
jumpered  to  *:XT  START  on  the  ADll-K  if 
mode  512  is  desired.  This  also  requires 
the  A  EVENT  OUT  from  the  KWll-K  clock 
trigger  jumpered  to  the  KW  overflow  on 
the  ADll-K  if  clock  driven  sweeps  are 
desired. 

The  format  of  the  ADSWP  call  is  as  follows: 

CALL  ADSWP  (Ibuf ,lbuf , [nbuf] , (mode] , [iprset] , [iefnl, [Idelay] , 
t ichn] , [nchn] ) 


ibuf 


A  40-word  array  initielized  by  the  SETIBF  routine.   The  first  two 
words  of  the  array  are  the  I/O  status  block  (lOSB) . 


Ibuf 


The  size  in  words  of  each  data  buffer.   All  data  buff>)rs  must  be 
equal  in  size  and  Ibuf  must  be  greater  than  0. 


nbuf 


The  number  of  buffers  to  be  filled.  If  nbuf  is  omitted  or  set 
equal  to  0,  indefinite  sampling  ocr  irs.  The  STPSWP  routine 
terminates  indefinite  sampling. 


mode 


Sampling  options.  The  default  is  0.  The  mode  bit  values  listed 
below  that  are  preceded  by  a  plus  sign  (+)  are  independent  and 
can  be  ADDed  or  ORed  together.  Those  values  not  preceded  by  a 
plus  sign  are  mutually  exclusive  and  only  one  such  value  can  be 
used  at  a  time.   All  bit  values  not  listed   elow  are  reserved. 

The  following  values  can  be  specified: 

0     Absolute  channel  addressing  (default).   This  mode  allows 
'       the   user   to   directly  access   all   63   channels  of  an 
ADll-K/AMll-K  combination.   This  is  the  only  mode   that 
is  LPA-ll  compatible. 
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1  Sampl*  with  a  gain  of  1.  In  modes  1,2,  3,  4,  and  S 
•ach  AD11-K/^M11-K  is  treated  as  Ifi  channels  with 
channels  17-f^j  strapped  to  gains  4,  16,  and  64.  The  48 
Multiplexer  channels  are  selected  by  the  software 
according  to  the  gain  specification.  Mode  values  1,  2, 
3,  4,  and  5  arc  not  supported  on  the  ADVll  (Q-bus 
version) . 

2  Gain  of  4.   See  also  mode  value  1. 

3  Gainofl6.   See  also  mode  value  1. 

4  Gain  of  64.   See  also  mode  value  1. 

§  Driver  will  perform  auto-gain  r&nging  to  return  the 
result  with  the  most  significance.  Note  that  use  of 
auto-gain  ranging  may  require  dual  sampling  and  will 
impact  performance.   See  also  mode  value  1. 

f  Use  user-supplied  interrupt  routine.   The   routine   must 

be  named  .ADINU  and  must  follow  the  interrupt  service 
routine  coding  conventions  used  in  this  subsystem. 
Refer  to  the  source  module  KADIN5.MAC  for  an  example  of 
an  A/D  interrupt  routine. 

♦256   External  start  (STl). 

♦512  Nonclock  overflow  sampling  triggered  by  STl. 


iprsat 


The  clock  preset.  The  clock  rate  divided  by  the  clock  preset 
value  yields  the  clock  overflow  rate.  The  XRATE  subroutine  can 
be  used  to  calculate  a  clock  preset  value.  If  the  iprset 
argument  is  omitted  from  the  ADSWP  call,  the  user  must  specify  a 
mode  value  of  +512.  Otherwise,  an  error  status  code  of  301 
(invalid  arguments)  is  returned  into  the  lOSB. 


lefn 


The  event  flag  (1-96),  a  completion  routine,  or  0.  If  0  or 
defaulted,  event  flag  30  will  be  utilized  for  internal 
synchronization.  If  iefn  is  an  event  flag  (1-96),  the  selected 
event  flag  is  set  as  each  buffer  is  filled.  If  iefn  is  greater 
than  96,  it  is  considered  to  be  a  completion  routine  that  will  be 
called  with  a  JSR  PC.  Such  routines  must  return  with  an  RTS  PC 
(or  a  FORTRAN  RETURN  statement).  Furthermore,  FORTRAN  completion 
routines  must  not  do  any  I/O  through  the  FORTRAN  runtime  system, 
since  this  may  cause  unpredictable  results  or  fatal  task  errors. 

If  multiple  sweeps  are  initiated,  the  user  should  specify 
different  event  flags.  Adherence  to  this  limitation  cannot  be 
enforced  by  the  software. 


Idelay 


The  delay  from  the  start  event  (STl)  until  the   first   sample   in 
IRATE  units.   Default  or  0  indicates  no  delay. 


• 
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Ichn 

The  number  of  the  first  channel  to  be  sampled.  The  default  of  0 
applies  only  if  ichn  was  not  established  in  a  prior  call  to  the 
SBTADC  routine. 

nchn 

The  numbwr  of  channels  to  sample.  The  default  is  1.  nchn  may  be 
set  up  with  the  SETADC  routine.  All  nchn  channels  will  be 
sampled  on  one  clock  interrupt. 

22.2.1.3  CLOCRAt  Set  Clock  A  Rate  -  The  CLOCKA  routine  sets  the   rate 
for  Clock  A.   The  format  of  the  call  to  this  routine  is  as  follows: 

CALL  CLOCKA  ( i rate , iprset , [ ind] , [ lun] ) 

irate 

The  clock  rate.   One  of  the  following  must  be  specified: 

0  Clock  B  overflow  (not  on  Q-bus  version)  or  no  rate 

1  1  MHz 

2  100  KHz 

3  10  KHz 

4  1  KHz 

5  IOC  Hz 

6  Schmitt  Trigger  1 

7  Line  frequency 


Iprset 


ind 


lun 


The  clock  preset.  The  clock  rate  divided  by  the  clock  preset 
value  yields  the  clock  overflow  rate.  The  XRATE  routine  can  be 
used  to  calculate  a  clock  preset  value. 


Receives  a  success  or  failure  code  as  follows: 

0  indicates  illegal  arguments. 

1  indicates  Clock  A  set  to  start  when  sweep  requested, 


The  logical   unit  number.    Present   for   LPA-11   compatibility. 
Ignored  by  K-series  software. 
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22.2.1.4  CLOCRBt  Control  Clock  B  -  Th«  CLOCKS  routine  gives  the  user 
control  over  the  KWll-K  Clock  B,  which  Is  used  to  maintain  a  16-blt 
software  clock.  This  feature  is  not  available  on  LSI~ll-bus  versions. 
The  16-blt  clock  Is  Incremented  once  per  Clock  B  Interrupt.  The 
Maximum  value  of  the  clock  is  65535. 

The  format  of  the  call  to  CLOCKB  is  as  followst 

CALL  CLOCKB  (( 1  rate | ,[ iprset] , [mode] ,( Ind] , [lun] ) 


irate 


The  clock  rate.  When  Irate  is  nonzero,  the  clock  is  set  rurrting 
at  the  selected  rate  after  the  preset  value  specified  by  Iprset 
Is  loaded.  The  16-bit  software  clock  is  not  altered  by  starting 
the  clock.  The  initial  value  of  the  16-bit  clock  is  0  when  the 
program  is  loaded. 

When  irate  is  0,  clock  B  is  stopped  but  the  16-bit  software  clock 
is  unaltered.  , 

When  irate  is  defaulted,  the  16-blt  software  clock  is  zeroed  but 
clock  B  continues  to  run. 

The  following  are  the  acceptable  values  for  irate: 

Q^  Stop  Clock  B 

I  IMHz 

t  100  KHz 

S  10  KHz 

#  1  KHz 
S  100  Hz 

#  Schmltt  Trigger  3 
7  Line  frequency 


iprset 


The  count  by  which  to  divide  clock  rate  to  yield  overflow  rate. 
Overflow  events  can  be  used  to  maintain  the  16-bit  software  clock 
and/or  drive  clock  A.  The  default  value  is  1.  The  maximum 
practical  overflow  rate  in  interrupt  mode  is  10  KHz.  The  range 
of  iprset  is  1-255.  The  value  in  iprset  can  be  established  by 
use  of  the  XRATE  routine. 


• 


22-12 


...-.  Li_,  .K«»K.' 


R-8BRIBS  PERIPHERAL  SUPPORT  ROUTINES 

■Od* 

The  options.   Either  of  the  following  can  b«  specified i 

0  indicates  normal  operations.  This  is  the  default.  The 
16-bit  software  clock  is  updated  on  Clock  B  overflow. 
The  overflow  rate  should  not  exceed  lOKHz.  The  software 
docs  not  check  the  overflow  rate. 

1  indicates  Clock  B  operates  in  noninterrupt  mode.  The 
16-bit  clock  is  not  incremented  or  altered.  This  allows 
a  greater  than  lOKHz  pulse  to  be  sent  to  clock  A. 

Ind 

Receives  a  success  or  failure  code  as  follows: 

0  indicates  a  failure  to  start  Clock  B. 

1  indicates  Clock  B  started. 


lun 


The  logical   unit  number.    This  argument   is   ignored   by  the 
K-series  routines.   It  is  present  for  LPA-11  compatibility. 


22.2.1.5  CVADPi  Convert  A/D  Input  to  Pleating  Point  -  The  CVADP 
routine  converts  an  A/D  input  value  to  a  floating-point  number.  The 
routine  can  be  invoked  as  a  subroutine  or  a  function  as  follows: 

CALL  CVADF  (ival,val) 


val  «  CVADF (ival) 

ival 

A  value  obtained  from  A/D  input.   Bits  12-15  are  the  gain.    Bits 
0-11  represent  the  value. 

val 

(REAL*4)  receives  the  converted  value. 
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22.2.1.(i  DASHPt  Initlat*  Synchronous  D/A  Swoop  -  The  DASWP   routino 
initiatos  synchronous  D/A  output  to  an  AAll-K. 

Ths  fomat  of  tho  DASWP  call  Is  as  follows: 

CALL  DASWP  (ibuf ,lbuf ,[nbuf] , [mode] , [iprsot] ,[l«fn] , [Idolay] , 
[ ichn] , [nchn] ) 


ibuf 


A  40-word  array  inltializad  by  the  SETIBP  routine.  The  first  two 
words  of  the  array  are  the  I/O  status  block  (lOSB). 


Ibuf 


Ths  slse  In  words  of  each  data  buffer.   All  data  buffers  must  be 
equal  In  size  and  Ibuf  must  be  greater  than  0. 


nbuf 


The  number  of  buffers  to  be  emptied.  If  nbuf  is  omitted  or  set 
equal  to  0,  indefinite  emptying  occurs.  The  STPSWP  routine 
terminates  indefinite  emptying. 


node 


The  start  criteria.  Except  where  noted,  the  plus  sign  (-•■) 
preceding  mode  bit  values  listed  below  indicates  that  they  are 
independent  and  can  be  added  or  ORed  together.  All  bit  values 
not  listed  below  are  reserved. 

The  following  values  can  be  specified: 

Q.     indicates  immediate*  start.   This  is  the  default. 

i  indicates  that  a  group  of  data  words,  whose  number  is 
specified  by  nchn,  is  preceded  by  a  scope  control  word 
(refer  to  Section  22.2.1.22  for  a  description  of  scope 
control  words).  This  bit  setting  is  ignored  if  ■«-512  Is 
also  specified.  This  feature  is  not  included  in  the 
Q-bus  (AAVll)  version.  , 

The  buffer  size  specified  by  Ibuf  must  be  a  multiple  of 
nchn+1  words.  The  DASWP  routine,  however,  does  not 
enforce  this  restriction. 

2  sets  the  Intensify  bit  after  each  pair  of  channels  (nchn 
must  be  2)  have  been  output.  This  feature  Is  supported 
on  the  Q-bus  version  only.  It  assumes  that  bit  0  of 
DAC3  on  the  AAVll  is  connected  to  the  intensify  input  on 
the  oscilloscope. 

4256   indicates  external  start  (STl). 
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+512  Indicates  non-clock-ov«rflow,  non-lnt«rrupt-driv«n 
output  (burst  mode).  This  value  cannot  be  specified 
with  either  external  start  (■«-256)  or  a  nonzero  Idelay 
value.  A  completion  routine  must  be  specified  If  nbuf 
Is  greater  than  the  number  of  buffers  supplied  or  If 
continuous  burst  output  Is  desired.  If  nbuf  equals  -1, 
burst  mode  must  be  stopped  by  calling  STPSWP  from  the 
completion  routine. 


Iprset 


The  clock  preset.  The  clock  rate  divided  by  the  clock  preset 
value  yields  the  clock  overflow  rate.  The  XRATE  subroutine  can 
be  used  to  calculate  a  clock  preset  value. 

If  the  Iprset  argument  is  omitted,  the  user  must  specify  a  mode 
value  of  ■t-512.  Otherwise,  an  error  status  code  of  301  (invalid 
arguments)  is  returned  into  the  lOSB. 


i«fn 


An  event  flag  number  (from  1  to  96),  or  a  completion  routine,  or 
0.  If  0  or  defaulted,  event  flag  30  is  used  for  internal 
synchronization.  If  iefn  is  an  event  flag  from  1  to  96,  the 
selected  event  flag  is  set  as  each  buffer  is  emptied.  If  iefn  is 
greater  than  96,  it  is  considered  a  completion  routine  that  will 
be  called  with  a  JSR  PC.  Such  routines  must  return  with  an  RTS 
PC  instruction  (or  a  FORTRAN  RETURN  statement).  Furthermore, 
FORTRAN  completion  routines  must  not  perform  I/O  through  the 
FORTRAN  run-time  system  since  this  may  cause  unpredictable 
results  or  fatal  task  errors. 

If  multiple  sweeps  are  initiated,  the  user  should  specify 
different  event  flags.  This  limitation  cannot  be  enforced  by  the 
software. 

• 

Idelay 

The  delay  .from  start  event  (STl)  until  the  first  sample  in  irate 
units.   Default  or  0  Indicates  no  delay. 

Ichn 

The  first  channel  number.   The  default  is  0. 


nchn 


The  number  of  channels.  The  default  is  1.  When  nchn  equals  2 
and  mode  does  not  contain  -fl,  the  size  of  data  buffers  specified 
in  Ibuf  must  be  an  even  number.  The  software  does  not  check  this 
requirement. 
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22.2.1.7  DIOOt  Digital  Start  Bvant  -  Tha  DIGO  routina  allowa  tha  uaar 
to  apaclfy  tha  digital  Input  bits  that,  whan  sat,  will  causa  tha 
simulation  of  an  axtarnal  start  avant  and  tha  start  of  a  pandlng 
smap. 

Tha  format  of  tha  call  to  DIGO  1st 

CALL  DIGO  ((lunlt] rtmask] , [kount] ) 

iunit 

Tha  DRll-K  unit  numbar.   The  dafault  is  0. 


■aak 


A  loglcol  r.ask  that  specifies  one  or  more  start  bits.  If  zero,  a 
pending  digital  start  event  request  Is  immediately  cancelled.  If 
defaulted,  an  ST'  event  is  immediately  simulated  and  the  current 
value  of  the  lifi-bit  software  clock  Is  returned  In  kount,  if 
specified. 


kount 


Receives  the  current  value  of  the  16-bit  software  clock  when   the 
defaulting  of  mask  causes  the  simulation  of  an  STl  event. 


22.2.1.8  DINPi  Digital  Input  -  The  DINP  routine  inputs  a  single 
16-blt  word  from  a  DRll-K.  Bits  read  as  a  1,  can  be  masked  with  a  1, 
causing  the  clearing  of  the  bit  in  the  DRll-K  input  buffer. 

During  the  K-serles  routines  generation  dialog,  it  is  possible  to 
select  one  of  two  version?}  of  the  DINP  routine: 

1.  A  slow  version  containing  all  functions  described  below 

2.  A  fast  ver5«lon  that  omits  the  functions  provided  by  the  mask, 
iosb,  and  input  a-juments 

The  fast  version  of  DINP  can  be  invoked  as  a  function  (IDINP)  only. 
The  slow  version  of  DINP  can  be  invoked  as  a  subroutine  or  a  function. 
The  formats  of  the  invocations  are  as  follows: 

CALL  DINP  ( [iunit] , [mask] , iosb, input) 

or 

lnd>IDINP( iunit, [mask] ,losb, [input] ) 


iunit 


The  DRll-K  unit  number.   This  argument  is  required  for   the   fast 
version  of  DINP.   For  the  slow  version,  the  default  is  0. 
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■ask 

Th«  bit  mask  used  to  specify  which  Input  bits  will  be  cleared  In 
the  digital  Input  register.  The  default  Is  1/7777)8)  IndlcotirQ 
all  bits  will  be  cleared. 

iosb 

A  2-word  I/O  status  block  array  (see  Section  22.2.3). 

input 

Receives  the  data  Input  from  the  ORll-K. 


Ind 


Receives  the  data  input  from  the  DRll-K  if  DINP  is  invoked   as   a 
function. 


22.2.1.9  DISWP:  Initiate  Synchronous  Digital  Input  Sv-^cp  -  The   DISWP 
routine  Initiates  a  synchronous  digital  Input  sweep  throuqh  a  DRll-K. 

The  format  of  the  call  to  DISWP  is: 

CALL  DISWP  (ibuf ,lbuf ,fnbuf] , fmode] , f Iprsetl , [iefn] , fldelay] , 
riunit] ) 


ibuf 


Ibuf 


A  40-word  array  initialized  by  the  SETIBF  routine.   The  first  two 
words  of  the  array  are  the  I/O  status  block  (lOSB). 


The  size  in  words  of  each  data  buffer.  All  data  buffers  mus*-  be 
equal  in  size  and  Ibuf  must  be  greater  than  0. 

nbuf 

The  number  of  buffers  to  be  filled.  If  nbuf  is  0  or  defaulted, 
indefinite  sampling  occurs.  The  STPSWP  routine  is  used  to 
terminate  indefinite  sampling. 

■ode  The  sampling  options.  The  default  is  0.  The  plus  signs  (-f) 
preceding  the  mode  bit  values  listed  below  indicate  that  they  are 
independent  and  can  be  added  or  ORed  together. 
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Th«  following  values  can  be  spocifiedt 

0  Slnglo-word  aanpla,  Immadlata  start.  This  is  ths 
default  mode. 

•f256   External  start  (STl). 

■f512  Nonclock  overflow  interrupt-driven  Input.  External 
•tart  and  delay  are  illegal. 

41024  Time-stamped  sampling.  The  double  word  consists  of  one 
data  word  followed  by  the  value  of  the  16-bit  software 
clock  at  the  time  of  the  sample.  This  option  is  not 
available  if  the  KWll-K  clock  is  not  being  used  (for 
example,  on  the  Q-bus) . 


iprset 


The  clock  preset.  The  clock  rate  divided  by  the  clock  preset 
value  yirlds  the  clock  overflow  rate.  The  XRATE  subroutine  can 
be  used  to  calculate  a  clock  preset  value. 

If  the  iprset  argument  is  omitted,  the  user  must  specify  a  mode 
value  of  ■f512.  Otherwise,  an  error  status  code  of  301  (invalid 
arguments)  is  returned  into  the  lOSB. 


lefn 


An  event  flag  number  (from  1  to  96),  or  a  completion  routine,  or 
0.  If  0  or  defaulted,  event  flag  30  is  used  for  internal 
synchronization.  If  iefn  is  an  event  flag  from  1  to  96,  the 
selected  event  flag  is  set  as  each  buffer  is  filled.  If  iefn  is 
greater  than  96,  it  is  considered  a  completion  routine  that  will 
be  called  with  a  JSR  PC.  Such  routines  must  return  with  an  RTS 
PC  instruction  (or  a  FORTRAN  RETURN  statement).  Furthermore, 
FORTRAN  completion  routines  must  not  perform  I/O  through  the 
FORTRAN  run-time  system  since  this  may  cause  unpredictable 
results  or  fatal  task  errors. 

If  multiple  sweeps  are  initiated,  the  usor  shold  speci  'y 
different  event  flags.  This  limitation  cannot  be  enforced  by  the 
software. 

Idelay 

The  delay  from  start  event  (STl)  until  the  first  sample  In  irate 
units.   Default  or  0  indicates  no  delay. 

iunlt 

The  DRll-K  unit  number.   The  default  is  0. 
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22.2.1.10  DOSWPt  Initiate  Synchronous  Digital  Output  Swaap  -  Tha 
DOSWP  routlna  initiataa  a  synchronous  digital  output  sweep  through  a 
DRll-K. 

The  format  of  the  call  to  DOSWP  Is  as  follows t 

CALL  DOSWP  (Ibuf ,lbuf,[nbufl , [model ,[lpr8et] ,(lefn] , [Idelay] , 
[iunit]) 


ibuf 


A  40-word  array  initialized  by  the  SETIBF  routine.   The  first  two 
words  of  the  array  are  the  I/O  status  block  (lOSB) . 


Ibuf 


The  sive  in  words  of  each  data  buffer.   All  data  buffers  must  be 
equal  in  size,  and  Ibuf  must  be  greater  than  0. 


nbuf 


The  number  of  buffers  to  be  emptied.  If  nbuf  is  0  or  defaulted, 
indefinite  emptying  occurs.  The  STPSWP  routine  Is  used  to 
terminate  indefinite  emptying. 

node 

The  start  criteria.   The  default  is  0. 

The  following  values  can  be  specified  in  the  high-order  byte  of 
mode: 

0     Immediate  start.   This  is  the  default. 

+256   External  event  start  (STl). 

+512   Nonclock  overflow,   interrupt-dr iven   output.    External 
start  and  delay  are  illegal. 


iprset 


The  clock  preset.  The  clock  rate  divided  by  the  clock  preset 
value  yields  the  clock  overflow  rate.  The  XRATE  subroutine  can 
be  used  to  calculate  a  clock  preset  value. 

If  the  iprset  argument  is  omitted,  the  user  must  specify  a  mode 
value  of  *512.  Otherwise,  an  error  status  code  of  301  (invalid 
arguments)  is  returned  into  the  lOSB. 
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l«fn 

An  event  flag  nuR'>«r  (from  1  to  96),  or  a  completion  routine,  or 
0.  If  0  or  defaulted,  event  iflag  30  is  used  for  internal 
synchronization.  If  iefn  is  an  event  flag  from  1  to  96,  the 
■elected  event  flag  is  set  as  each  buffer  is  emptied.  If  iefn  is 
greater  than  96,  it  is  considered  a  completion  routine  that  will 
be  called  with  a  JSR  PC.  Such  routines  must  return  with  an  RTS 
PC  instruction  (or  a  PORTRAK  RETURN  statement) .  Furthermore, 
FORTRAN  completion  routines  must  not  perform  I/O  through  the 
FORTRAN  run-time  system  since  this  may  cause  unpredictable 
results  or  fatal  task  errors. 

If  multiple  sweeps  are  Initiated,  the  user  should  specify 
different  event  flags.  This  limitation  cannot  be  enforced  by  the 
software. 

Idelay 

The  delay  from  start  event  (STl)  until  the  first  sample  in  irate 
units.   Default  or  0  indicates  no  delay. 

lunlt 

The  DRll-K  unit  number.   The  oefault  is  0. 


22.2.1.11  DOUTt  Digital  Output  -  The  DOUT  routine  outputs  a  single 
16-bit  word  to  a  DRll-K.  Only  those  bits  in  the  output  word  specified 
by  corresponding  ones  In  a  mask  field  are  altered. 

During  the  K-series  routines  generation  dialog,  it  is  possible  to 
select  one  of  two  versions  of  the  DOUT  routine: 

1.  A  slow  version  containing  all  functions  described  below 

2.  A  fast  version  that  omits  the  functions  provided  by  the  mask 
and  iosb  arguments 

The  slow  version  of  DOUT  can  be  invoked  as  a  subroutine  or  a  function. 
The  fast  version  of  DOUT  can  be  invoked  as  a  subroutine  only.  The 
formats  of  the  invocations  are  as  follows: 

CALL  DOUT  ([iunit] , [mask] , iosb, idata) 

or 

'*  ' 

iout-IDOUT( [iunit] , [mask] , Iosb, idata) 

iunit 

The  DRll-K  unit  number.   The  default  is  0. 

■ask 


Used  to  select   which   bits   can   be   altered.    The  default   is 
177777(8),  indicating  all  bits. 
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losb 

A  2-word  I/O  status  block  (see  Section  22.2.3). 

idata 

The  Ifi-blt  output  value  for  the  DRll-K.   A  1  sets  a  corresponding 
bit.   A  0  clears  the  corresponding  bit. 


lout 


Receives  a  copy  of  the  DRll-K  output  register  after  It  has  been 
altered. 


22.2.1.12  PLT16!  Convert  Unsigned  Integer  to  a  Real  Constant  -  The 
FLT16  routine  converts  an  unsigned  16-blt  Integar  to  a  real  constant 
(REAL*4).   It  can  be  invoked  as  a  subroutine  or  a  function  as  follows: 

CALL  PLT16  (lval,val) 

or 

val-FLT16(ival[,val) ) 

Ival 

An  unsigned  16-bit  integer. 

val 

The  converted  (REAL*4)  value. 


22.2.1.13  GTHIST:  Gather  Interevent  Time  Data  -  The  GTHIST  routine 
initiates  sampling  to  measure  the  elapsed  time  between  events.  The 
value  of  the  Clock  A  buffer/preset  register  at  the  time  of  ST2  firing 
is  stored  in  a  user-provided  buffer. 

GTHIST  is  an  optional  facility  that  must  be  explicitly  selected  during 
the  K-series  generation  dialog  prior  to  its  use  in  any  program.  The 
format  of  the  call  to  GTHIST  is  as  follows: 

CALL  GTHIST  (Ibuf ,lbuf , [nbuf ] , [mode] , [ iprset] , [ ief n] , [kount] ) 

ibuf 

A  40-word  array  initialized  by  the  SETIBF  routine.   The  first  two 
words  of  the  array  are  the  I/O  status  block  (lOSB) . 


Ibuf 


The  size  in  words  of  each  data  buffer.   All  data  buffers  must  be 
equal  in  size  and  Ibuf  must  be  greater  than  0. 
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nbuf 

Th«  number  of  buffers  to  be  filled.  If  nbuf  is  0  or  defaulted, 
indefinite  sampling  occurs.  The  STPSWP  routine  is  used  to 
terminate  indefinite  sampling. 

•ode 

The  sampling  options  as  follows: 

0  indicates  external  event  timing  without  Zero  Base.   This 
is  the  default. 

1  indicates  external  event  timing  with  Zero  Base.   This  is 
the  only  mode  supported  for  the  KWVll. 


iprset 


A  null  argument.  It  (s  present  only  to  maintain  compatibility 
with  other  sweep  routine  calling  sequences, 

lefn 

An  event  flag  number  (from  1  to  96),  or  a  completion  routine,  or 
0.  If  0  or  defaulted,  event  flag  30  is  used  for  internal 
synchronization.  If  iefn  is  an  event  flag  from  1  to  96,  the 
selected  event  flag  is  set  as  each  buffer  is  filled.  If  iefn  is 
greater  than  96,  it  is  considered  a  completion  routine  that  will 
be  called  with  a  JSR  PC.  Such  routines  must  return  with  an  RTS 
PC  instruction  (or  a  FORTRAN  RETURN  statement).  Furthermore, 
FORTRAN  completion  routines  must  not  perform  I/O  through  the 
FORTRAN  run-time  system  since  this  may  cause  unpredictable 
results  or  fatal  task  errors. 

If  multiple  sweeps  are  initiated,  the  user  should  specify 
different  event  flags.  This  limitation  cannot  be  enforced  by  the 
software. 

kount 

A  counter  used  by  GTHIST,  as  described  below. 

To  take  Post-Stimulus  Time  data,  set  mode  to  0.  STl  signals  the 
occurrence  of  a  stimulus  and  starts  the  clock  (that  is,  no  data  is 
taken  until  the  first  STl  occurs).  Each  response  is  signalled  by  ST2, 
and  the  buffer/preset  register  contents  are  placed  in  the  user  buffer. 
Each  STl  resets  the  counter  register  to  0,  and  increments  kount  by  1. 
Thus,  kount  keeps  track  of  the  number  of  stimuli  (STl  events).  Clock 
overflow  stops  the  clock.  The  clock  waits  for  the  next  STl  event 
before  restarting.  The  maximum  stimulus-response  interval  is  a 
function  of  the  clock  rate. 

To  obtain  Inter-Stimulus-Interval  data,  set  mode  to  1.  The  time 
between  successive  events,  as  signalled  by  ST2,  is  recorded.  The 
maximum  interevent  time  is  a  function  of  the  clock  rate.  When  clock 
overflow  occurs,  the  value  returned  on  the  next  ST2  firing  is 
177777(8)  and  KOUNT  is  incremented.  Thus,  kount  represents  the  number 
of  times  the  maximum  interevent  time  was  exceeded.  In  general,  the 
user  should  ignore  values  of  177777(8). 
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22.2.7.14   IBPSTSi  G*t  Buffer  Status  -  The   IBPSTS   routine   returns 
information  on  buffers  being  used  in  a  sweep. 

The  format  of  the  call  to  IBPSTS  is  as  follows: 

CALL  IBPSTS  (ibuf,istat) 

ibuf 

The  40-word  array  specified  in  the  call  that  initiated  a  sweep. 


istat 


An  array  with  as  many  elements  as  there  are  buffers  involved  in 
the  sweep.  The  maximum  is  R.  IBPSTS  fills  each  element  in  the 
array  with  the  status  of  the  corresponding  buffer.  The  possible 
status  codes  are  as  follows: 

•^1  indicates  that  the  buffer  is  in  the  device  queue.  That 
is,  it  is  waiting  to  be  filled  or  emptied. 

*l  indicates  that  the  buffer  is  in  the   user   queue.    That 

is,   it  is  full  of  data  (for  input  sweeps)  or  is  waiting 
to  be  filled  (for  output  sweeps). 

0  indicates  that  the  status  of  the  buffer  is  unknown. 
That  is,  it  is  not  the  current  buffer  nor  is  it  in 
either  the  device  or  the  user  queue. 

•1  indicates  that  a  service  routine  is  currently  using  the 
buffer. 


22.2.1.15   ICLOKB:  Read  16-bit  Clock  -  The  ICLOKB  function  returns  the 
contents  of  the  16-bit  software  clock  is  an  integer  value  to  the  user. 

The  format  of  the  ICLOKB  function  call  is  as  follows: 
itim"ICLOKB(0) 


itim 


Receives  the  curent  value  of  the   16-bit   software   clock   as   an 
unsigned  integer. 

NOTE 

MACRO-11  programm  s  need  not  establish 
an  argument  block  for  the  ICLOKB 
function.  The  current  value  of  the 
software  clock  is  returned  in  RO. 


22-23 


R-!9BRIB8  PBRIPRBRAL  SUPPORT  ROUTINBS 

22.2.1.16  IGTHUPi  Return  Buffer  Nuabcr  -  The  TGTBUP  routin«  returns 
the  number  of  the  next  buffer  to  use.  This  routine  shouli  be  called 
by  u-'er  co»p'e»lop  routines  to  det#rnino  the  next  buffer  to  access. 
It  should  not  be  used  if  an  event  flag  was  specified  in  the 
sweep-initiating  call.  Rather,  the  IWTBUF  routine  should  be  used  with 
event  flags. 

IGTBUP  can  be  invoked  as  a  subrof  ine  or  a  function.  The  formats  of 
the  invocations  are: 

CALL  IGTBUF  ( ibuf , ibuf no) 

or 

ibuf no-IGTBUF( ibuf [, ibuf no] ) 

ibuf 

The  40-word  array  specified  in  the  call  that  initiated  a  sweep. 


ibuf no 


Receives  the  number  of  the  next  buffer  to  access.   If  there  is  no 
buffer  in  the  queue,  ibufno  contains  -1. 


22.2.1.17  INXTBF:  Set  Next  Buffer  -  The  INXTBF  routine  alters  the 
normal  buffer  selection  algorithm.  It  allows  the  user  to  specify  the 
number  of  the  next  buffer  to  be  filled  or  emptied. 

INXTBF  can  be  invoked  as  a  subroutine  or  a  function.  The  formats  of 
the  invocations  are: 

CALL  INXTBF  ( ibuf , ibuf no [, ind] )  , 

or 

ind-INXTBF(ibuf ,ibufno(,indl ) 

ibuf 

The  40-word  array  specified  in  the  call  that  initiated  a  sweep. 

ibufno 

The  number  of  the  next  buffer  the  user  wants  filled   or   emptied. 
The  buffer  must  already  be  in  the  device  queue. 

ind 

Receives  an  indication  of  the  result  of  the  operation: 

■0     indicates  that  the  specified  buffer  was   already  active 
;*~   or  was  not  in  the  device  queue. 

—- 1^-   indicates  that  the  next  buffer  was  successfully  set.    - 


22-24 


K-SERIES  PERIPHERAL  SUPPORT  ROUTINES 

22.2.1.18  IWTBUFi  Wait  for  Buffar  -  The  IWTBIJF  routine  allows  a  I'jer 
task  to  wait  for  the  next  buffer  to  fill  or  empty.  It  should  b«  used 
in  conjunction  with  the  specification  of  an  event  tlag  in  the 
sweep-initiating  call.  Thii  routine  should  not  be  used  if  a 
completion  routine  was  specified  in  the  call  to  initiate  a  sweep. 
Rather,  the  IGTBUP  routine  should  be  used  with  completion  routines. 

IWTBUP  can  be  invoked  as  a  subroutine  or  a  function.  The  forma'-.s  of 
the  invocations  are  as  follows: 

CALL  IWTBUF  ( ibuf , [ ief n] , ibuf no) 


^bufno-IWTBUF(ibuf , fiefn] , [ibufnol ) 

Ibuf 

>  • 

The  40-word  array  specified  in  the  call  that  initiated  a  sweep. 

iefn     "    , 

The  event  flag  on  which  the  task  will  wait.  This  should  be  the 
same  event  flag  as  that  specified  in  the  sweep-initiating  call. 
If  iefn  equeils  0  or  is  defaulted,  event  flag  JO  is  used. 


ibufno 


Receives  the  number  of  the  nex   buffer  to  be  filled  or  emptied  by 
the  user's  task. 


22.2.1.19  RCLOKB:  Read  16-bit  Clock  -  The  RCLOKB  routine  returns  to 
the  user's  task  the  contents  of  the  16-bit  software  clock  as  a  real 
constant. 

RCLOKB  can  be  invoked  as  a  subroutine  or  a  function  as  follows: 

CALL  RCLOKB  (rlast,time) 

time-RCLOKB{rlast,time)  ^ 


time 


Receives  the  current  value  of  the  16-bit  software  clock  as  a  real 
constant  (REAL*4). 


rlast 


A  value   (REAL*4)   to   be   subtracted   from   the   current   16-bit 
software  clock  before  it  is  returned  into  the  time  field. 
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22.2.1.20  RLSBUFi  Release  Data  Buffar  -  The  RLSBUP  routine  declares 
one  or  more  buffers  free  for  use  by  the  Interrupt  service  routine. 

The  RLSBUF  routine  must  be  called  to  release  buffer(s)  to  the  device 
queue  before  the  sweep  is  initiated.  The  device  queue  must  always 
contain  at  least  one  buffer  to  maintain  continuous  sampling. 
Otherwise,  buffer  overrun  occurs  (see  Section  22.3  for  a  discussion  of 
buffer  management).  Note  that  RLSBUF  does  not  verify  whether  the 
specified  buffers  are  already  in  a  queue. 

The  format  of  the  call  to  RLSBUP  is  as  follows: 

CALL  RLSBUF  ( ibuf , ind  ,nO [ ,nl . .  .  ,n7] ) 

ibuf 

The  40-word  array  specified  in  the  call  that  initiated  a  sweep. 

Ind 

Receives  a  success  or  failure  code  as  follows: 

0  indicates  illegal  buffer  number  specified. 

1  indicates  buffer(s)  successfully  released. 

nO,nl,and  so  forth 

The  numbers  of  buffers  to  be  released.   A  maximum  of  eight  can  be 
specified. 


22.2.1.21   RMVBUF:   Remove   Buffer   from   Device   Queue  -  The    RMVBUF 
routine  removes  a  buffer  from  the  device  queue. 

The  format  of  the  call  to  RMVBUF  is  as  follows: 

CALL  RMVBUF  { ibuf ,n [,  ind] ) 


ibuf  y 

The  40-word  array  specified  in  the  call  that  Initiated  a  sweep. 


n 


ind 


The  number  of  the  buffer  to  remove. 


Receives  a  success  or  failure  code  as  follows: 

0  indicates  that  the   specified   buffer   was  not   in   the 
device  queue. 

1  indicates  that  the  specified  buffer  was  removed  from  the 
queue.  , 
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22.2.1.22   SCOPE:  Control  Scopi'  -  Th«  SCOPE  routine  allows  the  user  to 
control  the  status  reglst—  -'  n  AAll-K. 

The  format  of  the  call  to  SCOPE  Js  as  follows: 

CALL  SCOPE  (iunit,lcntrl,iosb) 


iunlt 


The  AAll-K  unit  number. 


Icntrl 


A  combination  of  bit  values  as  shown  In  Table  22-2.  Any  bits  not 
listed  in  this  table  are  cleared  before  output  to  the  AAll-K 
status  register 


iosb 


A  2-word  I/O  status  block  (see  Section  22.2.3). 


Table  22-2 
Scope  Control  Word  Values 


Decimal  Value 

Octal  Value 

Function 

4096 

10000 

Erase  storage  CRT 

2048 

4000 

Set  write-through  mode 

1024 

2000 

Set  store  mode 

512 

1000 

A  digital  signal   available 
the  AAll-K. 

in 

12 

14 

Intensify  on  X  or  Y 

8 

10 

Intensify  on  Y 

...'; 

4 

4 

■^   Intensify  on  X 

2 

2 

Fast  intensify  enable 

1 

1 

Intensify  pulse 

The  values  in  Table  22-2  are  also  used  to  create  scope  control   words 
for  calls  to  the  DASWP  routine  with  a  ii  de  value  of  1. 
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22.2.1.23   SETADCi  Set  Channel  Information  -  The    SETADC     routine 
establishes  channel  start  and  Increment  Information  for  an  A/D  sweep. 

SCTAOC  can  be  Invoked  as  a  subroutine  or  a  function  at   followst 
CALL  SETADC  ( ibuf , [ i f lag] , [ Ichn] , [nchn] , [ incl , [ ind] ) 

or 

ind  -  ISTADC(lbuf,[lflag) ,[lchn],[nchnl,tinc),{lndl) 

ibuf 

A  40-word  array  initialized  by  the  SETIBF  routine. 

iflag 

Equals  zero  if  the  user  wants  absolute  addressing  and  nonzero  for 
programmable  gain  addressing.   The  default  is  0. 

Ichn 

The  first  channel  number.   The  default  is  0. 

nchn  ■  /■''  ■'  ■  ■  ''■  •• 

The  number  of  samples  to  be  taken  per  interrupt.   The  default  is 

*  •  ■",„, '  ^■"' 

'  ,  '  '■  '  /'''■  ■  ''   '    '  ■ 

Inc  ,  ';>■.•.  ,.•','■■■ 

The  channel  increment.    The  default   is   1.    The   user   should 
specify  an  increment  of  2  for  differential  A/D  input. 

ind      ■' :^: "■■■■■:::':'  .'■■■'''''■  •      ■       '  ■'  .,,.,  .  .  '  ,  ■  ■;  ''■'''•  ,   ,  '''  - 

Receives  a  success  or  failure  code  as  follows: 

•0     indicates  an  illegal  channel  number. 

1     indicates  successful  recording   of  channel   information 
for  an  A/D  sweep. 

22.2.1.24   SETIBF:  Set  Array  for  Buffered  Sweep  -  The   SETIBF  routine 
initializes  an  array  required  by  buffered  sweep  routines. 

The  format  of  the  call  to  SETIBF  is  as  follows: 

CALL  SETIBF  ( ibuf , [ Ind] , [lamskb] ,buf 0 [ ,buf 1 . . .buf 7] ) 

ibuf   ■'-.;■  ■..:..,: -._ 

A  40-word  array. 


• 
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Receives  a  success  or  failure  code  as  follows: 

0  indicates  an  illegal  number  of  buffers  was  specified. 
SETIBF  initializes  the  array  according  to  the  maximum 
number  of  buffers  allowed.  This  maximum  number  of 
buffers  is  specified  by  the  user  during  the  K-series 
generation  dialog. 

1  Indicates  the  array  was  successfully  initialized. 


lamskb 


Present  for  compatibility  with  LPA-11  routines.  It  is  ignored  by 
K-series  software. 

bufo,  etc.        ' 

The  name  of  a  buffer.  A  maximum  of  eight  buffers  can  be 
specified.  Any  buffer  names  in  excess  of  eight  are  ignored.  At 
least  two  buffers  must  be  specified  to  maintain  continuous 
sampl ing . 

Each  buffer  specified  in  the  call  to  SETIBF  is  assigned  a  number  from 
0  to  7.  .  ,i 

The  assignment  of  these  numbers  is  based  on  the  order  in  which  buffer 
names  appear  in  the  argument  list.  The  first  buffer  whose  name 
appears  In  the  list  is  assigned  number  0,  the  second  is  assigned 
number  1,  and  so  forth.  Tn  all  subsequent  calls  to  other  K-series 
rout',  .es  involving  the  set  of  buffers  specified  in  a  call  to  SETIBF, 
these  numbers,  rather  than  names,  are  used  to  refei  to  particular 
buffers. 


22.2.1.25  STPSWP:  Stop  Sweep  -  The  STPSWP  routine  allows  the  user   to 
stop  a  sweep  that  is  in  progress. 

The  format  of  the  call  to  STPSWP  is  as  follows; 

CALL  STPSWP  (ibuf [,i when] , [ind] )  ■  ' 

ibuf 

The  40-word  array  specified  in  the  call  that  initiated  a  sweep. 

iwhen 

Specifies  when  to  stop  the  sweep: 

6     indicates  at  the  next  sample.   This  is  the  default. 

+n    (any  positive  value)  indicates  at  the  end  of  the  current 
buffer. 

-n    (any  negative  value)  is  reserved. 
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Receives  a  success  or  failure  code  as  follows: 

0  Indicates  that  the  sweep  was  not  active  or  no  sweep 
could  be  found  that  was  associated  with  the  speclfiea 
Ibuf. 

1  indicates  that  the  sweep  will  be  stopped  (at  the  time 
Indicated  by  Iwhen) . 


22.2.1.26  XRATE:  Compute  Clock  Rate  and  Pre  et  -  The  XRATE  routine 
computes  an  appropriate  clock  rate  and  preset  that  will  achieve  a 
desired  dwell  (intersample  Interval). 

NOTE 

The  XRATE  routine  can  be  used  only  on 
systems  that  have  a  FORTRAN  or 
BASIC-PLUS-2  compiler. 

XRATE  can  be  Invoked  as  a  subroutine  or  a  function  as  follows: 

CALL  XRATE  (dwell , 1  rate, iprset , 1  flag) 
or    .   ,    ■ 

adwell  =  XRATE(dwell, irate, iprset, iflag) 

dwell 

.  The  intersample  time  desired  by  the  user.   The  time  is   expressed 
in  decimal  seconds  (REAL*4) . 

irate 

Receives  the  computed  clock  rate  as  a  value  from  1  to  5. 

iprset 

Receives  the  clock  preset. 


iflag 


Specifies  whether  the  computation  is   intended   for   Clock   A  or 
Clock  B: 

0       indicates  the  computation  is  for  Clock  A. 

nonzero  indicates  the  computation  is  for  Clock  B. 


adwell 


The  actual  dwell  rate  for  the  clock  based  on  the  ir^-ite  and  iprset 
parameters. 
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22.2.2  HACRO-11  Interface 

MACRO-11  programmers  access  the  K-stries  support  routines  described  in 
Section  22.7.1    through  either  of  two  techniques: 

1.  The  standard  subroutine  linkage  mechanism  and   the  CALL  op 
code 

2.  Special -purpose  macros  that  generate   an   argument   list  and 
invoke  a  subroutine 

These  techniques  are  described  in  the  following  subsections. 


22.2.2.1   Standard   Subroutine   Linkage   and   CALL  Op  Code  -  K-series 

routines  can   be  accessed   through   use  of   the  standard  subroutine 

linkage  mechanism  and  the  CALL  op  code.   The  format  of  this  procedure 
is: 


arglist 


. PSECT 

code 

MOV 

#arglist,R5 

CALL 

ksubr 

.PSECT 

data 

.BYTE 

narg  ,0 

.WORD 

addrl 

; ARGUMENT  ADDRESS  TO  R5 
;CALL  K-SERIES  ROUTINE 

;NUMBER  OF  ARGUMENTS 
;FIP5T  ARGUMENT  ADDRESS 


.WORD 


addrn 


;LAST  ARGUMENT  ADDRESS 


In  this  sample,  the  two  PSECT  directives  are  shown  only  to  indicate 
the  noncontiguity  of  the  code  and  data  portions  of  the  linkage 
mechanism.  Within  the  argument  list,  any  argument  that  is  to  be 
defaulted  must  be  represented  by  a  -1  (that  is,  177777(8)). 


22.2.2.2  Special-Purpose  Macros  -  To  facilitate  the  calling  of 
K-series  support  routines  from  a  MACRO-11  program,  two  macros  are 
provided  in  file  [45, 10] LABMAC.MAC.   These  macros  are: 


1. 
2. 


INITS 
CALLS 


INITS  is  an   initialization  macro.    It   should   be   invoked   at   the 
beginning  of  the  MACRO-11  source  module. 


CALLS  invokes  a  K-seriec  supp.rt  routine, 
call  is  as  follows: 


The  format  of   this  macro 


CALLS  ksubr, ARGl, 


,ARGN> 


ksubr 


The  name  of  a  K-series  support  routine. 


argl,etc. 


^ 


Arguments  to  be  Cv-rmatted  into  an  argument  list  and  pasaed  to  tiie 
routine.  Each  argument  can  be  either  a  symbolic  name  or  a 
constant  (interpreted  -is  a  positive  decimal  number)  or  can  be 
defaulted . 
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22.2.3  The  I/O  Status  Block  (lOSB) 


Each  active  sweep  must  have  its  own  I/O  status  block.  The  I/O  status 
block  (lOSB)  is  a  2-worcl  array  allocated  in  the  user's  program.  It  is 
used  to  receive  the  status  of  a  call  to  a  K-series  support  routine. 
When  a  data  sweep  routine  is  called,  the  lOSB  is  always  the  first  two 
words  of  the  40-word  array  specified  as  the  first  argument  of  the 
call.  The  first  word  of  the  I03B  contains  the  status  code.  The 
second  word  contains  the  buffer  size  in  words. 


The  codes  that  can  appear  in  the  first  word  of  an  I/O  status  block  are 
in  ISA-compatible  format  (with  the  exception  of  the  I/O  pending 
condition).   Table  22-3  lists  all  return  codes. 


Table  22-3 
Contents  of  First  Word  of  lOSB 


lOSB  word  1 

Meaning 

0 

Operation  pending;   I/O  in  progress 

1 

Successful  completion 

301 

Invalid  arguments 

305 

Hardware  or  software  option  not  present 

306 

Illegal  buffer  specification 

313 

Data  overrun 

315 

Request  terminated 

317 

Resource  in  use 

397 

Invalid  event  flag 

2  2.3   BUFFER  MANAGEMENT 

The  management  of  buffers  for  data  sweeps  by  K-series  support  routines 
involves  the  use  of  two  FIFO  (First-In,  First-Out)  queues: 

1.  The  device  queue  (DVQ) 

2.  The  user  queue  (USQ) 

The  device  queue  (DVQ)  contains  the  numbers  of  all  buffers  that  the 
user  has  released  to  the  support  routines  in  a  call  to  RLSBUF.  The 
buffers  represented  by  these  numbers  are  ready  to  be  filled  with  data 
(input  sweeps)  or  to  be  emptied  of  data  (output  sweeps).  Any  buffer 
specified  in  a  call  to  INXTBF  must  already  be  in  DVQ. 


22-32 


K-SERIES  PERIPHERAL  SUPPORT  ROUTINES 

The  user  queue  (USQ)  contains  the  numbers  of  buffers  available  to  the 
user.  For  output  sweeps,  this  queue  contai.is  the  numbers  of  buffers 
that  have  already  been  emptied  by  the  driver.  For  input  sweeps,  the 
buffers  represented  by  USQ  are  those  which  arr  filled  with  data.  In 
both  instances,  the  user's  task  detemines  tha  next  buffer  to  use 
(that  is,  extracts  the  first  element  of  USQ)  by  calling  IGTBUF  or 
IWTBUF. 

Both  the  DVQ  and  USQ  are  initialized  to  -1,  indicating  no  buffers, 
when  the  user's  task  calls  the  SETIBF  routine.  The  task  must  call 
RLSBUF  before  initiating  any  sweep,  since  at  least  one  buffer  must  be 
present  in  DVQ  for  the  first  input  or  output  to  occur. 

For  input  sweeps,  the  best  strategy  is  to  call  RLSBUF,  specifying  the 
numbers  associated  with  all  the  buffers  to  be  used  in  the  sweep. 

For  output  sweeps,  one  approach  is  to  specify  two  buffers  (for 
continuous  sweeps)  in  the  call  to  RLSBUF.  The  first  action  then  taken 
either  in  a  completion  routine  or  after  a  call  to  IWTBUF  would  be  to 
release  the  next  buffer.  Note,  however,  that  this  approach  does  not 
represent  true  multiple  buffering,  since  data  overrun  occurs  if  the 
second  buffer  is  not  released  in  time. 


2  2.4   SAMPLE  FORTRAN  PROGRAMS 

Two  sample  FORTRAN  programs  showing  the  use  of  K-series  support 
routines  are  presented  in  this  section  The  first  program  uses  event 
flags  for  internal  synchronization.  The  second  program  demonstrates 
the  use  of  user-supplied  completion  routine  for  synchronization. 

NOTE 

FORTRAN  completion   routines   must   not 
contain  any  of  the  following: 

•  Any  I/O  through  the  FORTRAN  tun-time 
system 

•  Any  use  of  virtual  arrays 

•  Any  use  of  floating-point  operations 

•  Any  errors,  since  error  reporting  is 
done  through  the  FORTRAN  run-time 
system 

•  Anything  else  that  may  change  the 
FORTRAN  impure  area 


Any  of  the  above  may  result  in   fatal   task   errors   or   unpredictable 
results. 
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22.4.1  Sample  Program  Using  Event  Flag 

^   ■  '   '      IMPLICIT  INTEGER  (A-Z) 

DIMENSION  BUF(1024, 8) ,  IBUF  (40),  I0SB(2) 
:     EQUIVALENCE  ( IBUF ( \ ) , lOSB ( 1) ) 

■  e 

C.  INITIALIZE  THE  IBUF  ARRAY  FOR  THE  A/D  SWEEP 


d 


CALL  SETIBP  (IBUF,IND,  ,  BUF (1 , 1 ) ,  BUF(1,2),  BUF(1,3), 
*  BUF(}.,4),  BUF(1,5),  BUF(1,6),  BUF(1,7),  BUF(1,8)) 


WRITE  (1,  900) 

READ  (1,  910)  IRATE,  IPRSET 
C 

C  SET  THE  CLOCK  RATE  AND  PRESET  FOR  THE  SWEEP 

C 

CALL  CLOCKA  (IRATE,  IPRSET, IND) 
C 

C  THIS  IS  INPUT,  Sr  RELEASE  ALL  BUFFERS  TO  SERVICE 

C  ROUTINE 

C 

CALL  RLSBUF  (IBUF, IND,  0,1,2,3,4,5,6,7) 
C 

C  START  THE  SWEEP.  USE  1024  WORD  BUFFERS,  SAMPLE 

C  FOREVER,  EXTERNAL  START,  EVENT  FLAG  30,  1  CHANNEL  (0) 

C 

CALL  ADSWP  (IBUF,  1024,  -1,  256,  IPRSET, 

♦  30,  0,  C,  1) 

C 

C  HERE  WE  COULD  CHECK  THE  I/O  STATUS  BLOCK  TO  ENSURE 

C  THAT  THE  SWEEP  IS  ACTUALLY  RUNNING. 

C 

IBFCNT=0 
C 

C  THIS  IS  THE  TOP  OF  THE  DATA  PROCESSING  LOOP.  WE 

C  WAIT  FOR  A  BUFFER  TO  BE  COMPLETED,  AND  THEN  DUMP 

C  THE  FIRST  100  WORDS  OF  THE  BUFFER  TO  LUN  1. 

C 

10        IBUFNO  =  IWTBUF(IBUF,  30)+l 
C 

C  IWTBUF  WILL  RETURN  A  POSITIVE  BUFFER  NUMBER 

C  AS  LONG  AS  THERE  IS  A  BUFFER  OF  DATA  AVAILABLE. 

C  IF  IND  IS  -1,  WE  PROBABLY  HAD  DATA  OVERRUN,  SO  STOP. 

C 

IF  (IBUFNO  .EQ.  0)  STOP 
IBFCNT=IBFCNT+1 
WRITE  (1,920)  IBFCNT 

WRITE  (1,930)  (BUF(I, IBUFNO) ,  1=1,100) 
C 

C  RELEASE  BUFFER  FOR  SERVICE  ROUTINE  TO  REFILL 

C 

CALL  RLSBUF (IBUF, IND, IBUFNO-1) 
GOTO  10 
900       FORMAT  ('  ENTER  IRATE,  IPRSET:',  $) 
910       FORMAT  (T,  0) 

920       FORMAT  ('  DUMP  OF  BUFFER  NUMBER  ',^5,/) 
930       FORMAT  (1X,1007) 
END 
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22.4.2  Sample  Program  Using  Completion  Routine 

IMPLICIT  INTEGER  (A-Z) 
EXTERNAL  AST 

DIMENSION  BUF(1024, 8) ,  IBUF  (40),  I0SB(2) 
COMMON  /KDATA/  BUF,  IBUF,  IBFCNT 
EQUIVALENCE  (IBUF( 1 ) , lOSB ( 1 ) ) 

C 

C  INITIALIZE  THE  IBUF  ARRAY  FOR  THE  A/D  SWEEP 


C 


C 


CALL  SETIBF  (IBUF,IND,  ,  BUF(1,1),  BUF(1,2),  BUF(1,3), 
*  BUF(1,4),  BUF(1,5),  BUF(1,6),  BUF{1,7),  BUF(1,8)) 


WRITE  (1,  900) 

READ  (1,  910)  IRATE,  IPRSET 
C 

C  SET  THE  CLOCK  RATE  AND  PRESET  FOR  THE  SWEEP 

C 

CALL  CLOCKA  (IRATE,  IPRSET, IND) 
C 

C  THIS  IS  INPUT,  SO  RELEASE  ALL  BUFFERS  TO  SERVICE 

C  ROUTINE 

C 

CALL  RLSBUF  (IBUF, IND,  0,  1,  2,  3,  4,  5,  6,  7) 
C 

C  START  THE  SWEEP.  USE  1024  WORD  BUFFERS,  SAMPLE 

C  FOREVER,  EXTERNAL  START,  EVENT  FLAG  30,  1  CHANNEL 

(0). 

c 

IBFCNT  =  0 

CALL  ADSWP  (IBUF,  1024,  0,  256,  IPRSET 

*  AST,  0,  0,  1) 

C 

C  HERE  WE  COULD  CHECK  THE  I/O  STATUS  BLOCK  TO  ENSURE 

C  THAT  THE  SWEEP  IS  ACTUALLY  RUNNING. 

C 

10        CALL  WAITFR  (23) 
C 

C  WHEN  EVENT  FL..3  23  IS  SET  THE  SWEEP  IS  COMPLETED. 

C  WE  MAY  EXIT  NOW. 


STOP 


900       FORMAT  ('  ENTER  IRATE,  IPRSET:',  $) 
910       FORMAT  (I,  0) 

END 

SUBROUTINE  AST 
C 

C  THIS  SUBROUTINE  IS  CALLED  AT  AST  LEVEL  WHENEVER 

C  A  BUFFER  IS  COMPLETED.  THIS  ROUTINE  PROCESSES 

C  THE  CONTENTS  OF  THE  BUFFER  AND  THEN  RELEASES 

C  IT  FOR  THE  SERVICE  ROUTINE.  IF  THE  SWEEP  IS  TO 

C  TERMINATE  (lOSB  NON-ZERO)  THEN  EVENT  FLAG  23.  IS 

C  SET  TO  INDICATE  TO  THE  MAINLINE  CODE  THAT  WE  ARE 

C  DONE. 

IMPLICIT  INTEGER  (A-Z) 

DIMENSION  BUF(1024, 8) ,  IBUF(40),  I0SB(2) 

COMMON  /KDATA/  BUF,  IBUF,  IBFCNT 

EQUIVALENCE  ( IBUF ( 1 ) , lOSB ( 1 ) ) 

IBUFNO  =  IGTBUF  (IBUF)  +1 

IF  (IBUFNO-1)  .GE.  0  GOTO  20 
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IF  (lOSB(l)  .EQ,  0^  PAUSE  'INCONSISTENT  STATE' 

CALL  SETEF  (23) 

RETURN 

20         IBPCNT  =  IBFCNT  +  1 

C 

C  HERE  WE  WOULD  PROCESS  THE  DATA 

C 

c 

C  RELEASE  BUFFER  FOR  SERVICE  ROUTINE 

C 

CALL  RLSBUF  (IBUF,  IND,  IBUFNO-1) 

RETURN 

END 
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CHAPTER  23 
UNIBUS  SWITCH  DRIVER 


23.1   INTRODUCTION 

The  UNTBUS  switch  driver  supports  DT07  UNIBUS  switch  hardware  on 
RSX-llM-PLUS  systems.  UNIBUS  switches  are  electronic  devices  that 
allow  peripherals  to  be  switched  from  one  CPU  to  another,  enabling 
CPUs  to  share  peripheral  devices.  UNIBUS  switches  also  facilitate 
on-line  system  backup  and  allow  dynamic  reconfiguration  of  systems  in 
which  high  availability  of  certain  peripherals  is  required. 


k3.1.1   DT07  UNIBUS  Switches 

DT07  UNIBUS  switches  can  provide  two,  three,  or  four  ports  for 
connecting  an  external  UNIBUS  run  to  one  of  two,  three,  or  four  CPUs. 

Any  CPU  can  request  connection  to  a  UNIBUS  run  and  receive  the 
cor  ction  immediately  if  the  requested  UNIBUS  run  is  in  the  neutral 
ste,  ,  (it  is  not  connected  to  another  CPU's  UNIBUS).  If  the  request 
is  received  when  the  UNIBUS  run  is  connected  to  another  CPU,  an 
interrupt  is  generated,  informing  the  connected  CPU  of  the  pending 
request,  and  a  watchdoj  timer  is  started.  The  connected  CPU  normally 
acknowledges  the  request,  indicating  the  UNIBUS  is  still  in  use.  In 
this  case,  the  UNIBUS  remains  connected  to  the  CPU.  however,  if  the 
CPU  does  not  respond  to  the  interrupt  within  the  time  limit  imposed  by 
the  DT07's  watchdog  timer,  the  UNIBUS  is  switched  to  the  requesting 
CPU.  Thus,  a  CPU  that  is  not  operating  remains  connected  to  the 
UNIBUS  only  until  another  CPU  requests  the  UNIBUS. 

EaTh  DT07  UNIBUS  switch  port  functions  as  an  isolation  circuit.  When 
its  power  is  off,  it  does  not  affect  any  CPU  operation. 


23.1.2   UNIBUS  Switch  Driver 

The  UNIBUS  switch  driver  permits  the  UNIBUS  switch  to  be  used   in   one 
of  two  ways: 

1.  A  CPU  retains  the  UNIBUS  until  the  task  issuing  the 
directives  that  connected  the  UNIBUS  to  this  CPU  exits.  This 
is  normally  accomplished  when  the  task  attaches  the  UNIBJS 
switch  (10. ATT  function)  and  issues  the  connect  function 
(10. CON) ,  When  the  task  exits  (for  any  reason),  the  system 
detaches  the  UNIBUS  switch  (lO.DET)  and  perforins  an  implicit 
disconnect  function  (lO.DIS),  releasing  the  UNIBUS  switch  for 
use  by  any  other  task. 
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The  task  that  attaches  the  UNIBUS  switch  can  be  considered 
the  manager  of  the  UNIBUS  switch  until  the  task  exits.  The 
task  can  receive  ASTs  for  certain  conditions  involving  UNIBUS 
switching  (see  Jection  23.3.1.1). 

A  CPU  retains  the  UNIBUS  until  a  task  is  executed  that 
explicitly  disconnects  the  UNIBUS.  This  Is  normally 
accomplished  when  a  task  issues  the  10. CON  function  and  no 
previous  10. ATT  was  issued.  Once  the  UNIBUS  is  connected, 
the  task  exits.  The  UNIBUS  then  remains  connected  until 
either  the  CPU  fails  to  respond  to  other  CPU  requests  for  the 
UNIBUS,  or  a  task  is  executed  that  explicitly  disconnects  the 
UNIBUS.  Note  that  when  operating  in  this  manner,  no  active 
task  is  required  in  order  to  retain  the  UNIBUS. 


23.2   GET  LUH  INFORMATION  MACRO 


Word  2  of  the  buffer  filled  by  the  Get  LUN  Information  system 
directive  (the  first  characteristics  word)  contains  all  Os.  Words  3, 
4,  and  5  are  undefined. 


2  3.3   QIO  MACRO 

This  section  summarizes  standard  and  device-specific  QIO  functions  for 
UNIBUS  switches. 


23.3.1   Standard  QIO  Functions 

Table  23-1  lists  the  standard  functions  of   the   QIO  maco   that   are 
valid  for  UNIBUS  switches. 


Table  23-1 
Standard  QIO  Functions  for  UNIBUS  S'.'itches 


Format 

Function 

QIOSC    IO.ATT,...,<[ast]> 
QIOSC    lO.DET,... 
OIOSC    lO.KIL,... 

ATTACH  device 
Detach  device 
Cancel  I/O  requests 

ast 

The  address  of  an  optional  AST  routine  which  will  be   entered   if 
certain  conditions  are  detected  (see  Section  23.3.1.1) 

10. ATT   does   not   connect   the   UNIBUS   switch   (see   device-specific 
function  10. CON) . 


lO.DET  detaches  the  UNIBUS  switch  from  the  task.  If  the  UNIBUS  switch 
was  previously  attached  by  the  10. CON  function,  dn  implied  disconnect 
(lO.DIS)  iunctl'^r.  is  performed. 
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The  only  I/O  requests  that  can  be  affected  by  the  lO.KIL  function  are 
10. CON  and  10. DPT.  When  lO.KIL  is  issued  during  an  10. CON  function, 
further  retries  are  canceled.  When  lO.KIL  is  issued  during  an  10. DPT 
function,  the  time-out  count  is  changed,  forcing  time-out  (lE.TMO)  to 
occur. 


23.3.1.1  10. ATT  -  The  10. ATT  QIO  function  attaches  the  UNIBUS  switch 
to  the  task  issuing  the  QIO  directive.  An  optional  AST  address 
parameter  can  be  specified.  However,  if  it  is  specified,  it  must 
remain  valid  while  the  UNIBUS  switch  remains  attached  to  the  task. 

The  AST  service  routine  for  the  UNIBUS  switch  is  entered  when  one  of 
the  following  conditions  occur: 

•  The  UNIBUS  switch  has  become  connected  to  another  CPU  because: 

1.  The  operator  manually  switched  the  UNIBUS  to  another  CPU, 
or 

2.  This  CPU  failed  to  respond  to  another  CPU's  request  for 
the  UNIBUS  within  the  specified  time  (the  CPU  must 
acknowledge  the  request  by  servicing  an  interrupt,  as 
described  in  Section  23.1.1). 

UNIBUS  switch  condition  code  1  is  passed  to  the  AST  routine  by 
the  stack,  indicating  the  cause  of  the  AST. 

•  The  UNIBUS  switch  has  disconnected  from  the  CPU  because: 

1.  A  power  failure  occurred  in  this  CPU  (system  tower 
failure)  and  the  UNIBUS  switch  driver  was  unable  to 
reconnect  the  bus,  or 

2.  A  power  failure  occurred  on  the  connected  UNIBUS,  causing 
the  driver  to  automatically  disconnect  the  UNIBUS 

UNIBUS  switch  condition  code  2  (for  a  system  power  failure)  or 
condition  code  3  (for  a  UNIBUS  power  failure)  is  passed  to  the 
AST  routine  by  the  stack  indicating  the  cause  of  the  AST. 


23.3.1.2  lO.DET  -  Ti.a  lO.DET  function  detaches  the  issuing  task  from 
the  UNIBUS  switch,  and  in  addition,  performs  an  implied  disconnect  for 
the  issuing  task  if  that  task  had  connected  the  UNIBUS  switch.  A 
detach  function  is  generated  by  the  Executive  on  behalf  of  an  attached 
task  if  that  task  exits  (normally  or  abnormally)  without  explicitly 
detaching  the  device.  For  a  switched  UNIBUS,  this  causes  it  to  be 
disconnected  if  an  attached,  connected  task  faults  in  such  a  w^y  as  to 
cause  it  to  exit. 


23.3.1.3   lO.KIL  -  The  lO.KIL  function   will   cancel   any   outstanding 

10. CON   function   that  has  a  nonzero  retry  count  and  any  outstanding 

10. DPT  function  that  has  not  yet  timed  out.  Other   QIO   functions   in 

progress  are  not  affected  by  lO.KIL,  and  are  automatically  completed. 
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23.3.2  Device-Specific  QIO  Functions 

The  device-specific  functions  of  the  QIO  macro  that  are  valid   for 
UNIBUS  switches  are  shown  in  Table  23-2. 


Table  23-2 
Device-Specific  QIO  Functions  for  UNIBUS  Switches 


Format 

Function 

QIO$C 

10. CON, . . . ,<[rcnt] , Tcpu] > 

Connect  UNIBUS  switch 

QIOSC 

IO.DIS,...,<rtcut] , [port]> 

Disconnect  UNIBUS  switch 

0IO$C 

10. DPT, . . . ,< [tout] , [port]  > 

Disconnect  UNIBUS  switch 
from  specified  CPU  port 

0IO$C 

lO.SWI, . . . ,<cpu> 

Switch  the  UNIBUS  from 
current  CPU  to  specified  CPU 

0IO$C 

lO.CSR, . . . 

Read  UNIBUS  switch  CSR 

rent 


cpu 


port 


The  number  of  additional  times  the  connect  will  be  attempted   if 
the  lO.CON  fails  to  complete. 


The  ASCII  letter  designating   the  CPU   to   receive   the   UNIBUS 
switch. 


The  port  number,  ranging  from  0  through  3,  of  the  target  CPU  that 
must  request  the  bus  prior  to  the  CPU  that  is  currently  connected 
t>  the  UNIBUS  actually  completing  the  disconnect.  The  port 
number  corresponds  to  the  four  MANUAL  CONNECT  switch  positions 
(PORT  0  through  PORT  3)  marked  on  the  DT07  control  panel. 


tout 


The  maximum  time  (in  seconds)  allowed   (253.   maximum)   for   the 
function  to  be  completed  before  an  error  condition  is  reported. 

Parameter  details  are  included  in  the  following  sections. 


23.3.2.1  10. CON  -  The  10. CON  (connect)  function  requests  connection 
of  a  UNIBUS  presently  not  connected  to  a  specified  CPU.  It  can  be 
Issued  either  by  a  task  previously  attached  with  the  10. ATT  function 
or  by  a  task  that  is  not  attached.  The  10. CON  function  has  four 
optional  parameters.  The  use  of  each  parameter  is  described  as 
follows . 

Retry  Count  —  The  retry  count  specifies  the  number  of  additional 
times  the  connect  function  will  be  attempted  if  the  10. CON  fajls  to 
complete  within  the  time-out  period  of  the  UNIBUS  switch.  Retry  count 
parameters   used   in   this  manner  are  always  nonzero  positive  values. 
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The  10. CON  function  is  not  completed  until  either  the  retry  count 
expires  or  the  UNIBUS  switch  is  successfully  connected.  Thus,  the 
issuing  task  having  a  nonzero  retry  count  wil  not  be  checkpointed 
until  the  10. CON  function  is  completed. 

When  a  retry  count  of  0  is  specified,  the  connect  function  attempts  to 
connect  the  UNIBUS  switch  once  (no  retries)  and  immediately  reports 
the  directive  status  to  the  issuing  task. 

When  a  retry  count  of  177777  (-1)  is  specified,  the  connect  function 
continues  to  retry  the  connection  until  a  successful  connection  is 
made  or  an  lO.KIL  function  is  issued. 

CPU  —  The  CPU  parameter  can  only  be  used  with  loosely  coupled^ 
multiprocessor  systems  to  specify  the  CPU  to  which  the  UNIBUS  switch 
should  be  connected.  This  function  is  used  only  when  the  UNIBUS 
switch  is  presently  not  connected  (the  lO.SWI  function  should  be  used 
to  disconnect  the  UNIBUS  switch  from  a  connected  closely  coupled  CPU 
and  connect  it  to  a  specified  closely  coupled  CPU).  The  CPU  is 
specified  by  a  single  ASCII  letter  (A,  B,  C,  or  D) . 


23.3.2.2   lO.DIS  -  The  lO.DIS   function   is   used   to  disconnect   the 
switched  UNIB"S  from  the  currently  connected  CPU. 

NOTE 

It  is  the  responsibility  of  the  task 
issuing  the  lO.DIS  or  10. DPT  function  to 
determine  that  all  devices  on  the 
switched  UNI3US  are  inactive  when  the 
function  is  issued.  The  UNIBUS  switch 
driver  does  not  check  for  active  devices 
on  the  UNIBUS  before  completing  either 
the  lO.DIS  or  10. DPT  function. 


23.3.2.3  10. DPT  -  The  10. DPT  function  is  used  in  a  loosely  coupled^ 
multiprocessor  system  to  allow  the  UNIBUS  to  be  connected  to  another 
CPU  on  a  specified  port  if  the  CPU  requests  connection  within  a 
specified  time  interval.  (Refer  to  the  note  at  the  end  of  Section 
23.3.2.2.) 

Time-out  —  The  time-out  parameter  specifies  the  maximum  time  allowed 
for  the  function  to  complete  before  an  error  is  reported.  Time-out 
specifications  are  positive,  nonzero  values  ranging  from  1  to  254 
seconds.  The  default  time-out  value  is  2  seconds.  If  the  CPU 
parameter  is  included  in  the  10. DPT  function,  the  driver  waits  for  the 
specified  CPU  to  request  the  UNIBUS  up  to  the  specified  time-out 
value.  If  the  CPU  does  not  request  the  UNIBUS  during  this  time,  the 
UNIBUS  remains  connected  and  the  lE.TMO  status  is  returned  to  the 
issuing  task. 


1.  A  loosely  coupled  system  is  one  in  which  memory  resources  are  not 
shared  by  more  than  one  CPU. 
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If  a  time-out  value  of  0  is  specified,  the  lO.DIS  function  will  not 
complete  until  either  the  successful  disconnect  occurs,  or  an  lO.KIL 
function  is  issued. 

Port  —  The  port  parameter  can  only  be  used  with  loosely  coupled 
multiprocessor  systems  to  specify  the  port  through  which  the  UNIBUS 
switch  should  be  connected  to  a  CPU.  The  port  is  specified  by  a 
number  ranging  from  0  through  3. 


23.3.2.4  lO.SWI  -  The  lO.SWI  function  disconnects  the  UNIBUS  switch 
from  the  currently  connected  CPU  and  connects  it  to  the  specified  CPU 
in  a  closely  coupled  system.   The  CPU  parameter  is  required. 

lO.SWI  is  executed  without  the  possibility  of  a  third  CPU  taking 
control  of  the  UNIBUS  during  the  switching  process. 

The  CPU  parameter  is  used  in  closely  coupled  multiprocessor  systems  to 
specify  the  CPU  to  which  the  UNIBUS  switch  should  be  connected.  The 
CPU  is  specified  by  a  single  ASCII  letter  (A,  B,  C,  or  D) . 


23.3.2.5  lO.CSR  -  The  lO.CSR  function  reads  maintenance  information 
contained  in  the  device  CSR  and  returns  it  in  the  second  word  of  the 
I/O  status  block.  Information  returned  is  valid  only  if  the  UNIBUS 
switch  is  connected.  The  use  of  this  function  should  be  limited  to 
diagnostic  applications. 


23.4   POWER- FAIL  RECOVERY 

23.4.1   System  Power-Fail  Recovery 

During  power-fail  recovery,  the  driver  attempts  to  restore  the  state 
of  the  system  prior  to  the  actual  power  failure.  If  the  UNIBUS  switch 
is  found  to  be  disconnected  during  power-fail  recovery,  the  driver 
attempts  to  reconnect  the  switched  UNIBUS.  If  the  first  attempt  to 
reconnect  the  UNIBUS  is  not  successful,  an  entry  is  made  in  the  error 
log  and  the  attached  task  is  notified  of  the  UNIBUS  switch  state  by 
the  AST  specified  in  the  10. ATT  function  (if  previously  issued). 

If  an  10. CON  function  was  in  progress  when  the  power  failure  occurred 
and  a  retry  count  was  pending,  the  UNIBUS  switch  driver  attempts  to 
successfully  connect  the  UNIBUS  switch  until  the  retry  cour   expires. 

If  an  lO.DIS  or  10. DPT  function  was  in  progress  when  the  power  failure 
occurred,  the  UNIBUS  switch  driver  attempts  to  complete  the  operation. 


23.4.2   UNIBUS  Power-Fail  Recovery 

If  an  interrupt  is  received  from  the  UNIBUS  switch  indicating  a  power 
failure  has  occurred  on  the  switched  UNIBUS,  the  driver  issues  an 
immediate  disconnect  (lO.DIS).  The  attached  task  (if  any)  is  notified 
by  the  AST.  Note  that  the  system  may  be  corrupted  if  some  of  the  I/O 
devices  on  the  switched  UNIBUS  were  active  when  the  power  failure 
occurred,  since  the  drivers  for  those  I/O  devices  may  attempt  to 
access  the  device  registers  after  the  switched  UNIBUS  (and  I/O 
devices)  has  become  disconnected. 
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23.5   STATUS  RETURNS 


Table  23-3  lists  the  error  and  status  conditions  that  are  reti'rned   by 
the  UNIBUS  switch  driver. 


Table  23-3 
UNIBUS  Switch  Driver  Status  Returns 


fode 

Reason 

IS. sue 

Successful  completion 

The  operation  specified   in   the   QIO  directive   was 

con.pleted  successfully. 

IS.PND 

I/O  request  pending 

The  operation  specified  in  the  QIO  directive  has  not 

yet   been   executed.    The  I/O  status  block  is  filled 

with  Os. 

IE. ABO 

Request  aborted 

An  I/O  request  was  queued  (not  yet  acted  upon  by  the 

driver)  when  an  lO.KIL  was  issued. 

IE. BAD 

Bad  parameters 

The  parameters  specified  in  the   QIO  macro  were   in 

error. 

IE. CNR 

Connect  rejected 

The  connect  function  did  not  successfully  connect  the 

switched   UNIBUS   to  the  specified  CPU,  and  the  retry 

count,  if  specified,  has  expired. 

lE.DAA 

Device  already  attached 

The  device  specified  in  an  10. ATT  funcion  was  already 

attached   by  the   issuing  task.   This  code  indicates 

that   the   issuing   task  has   already  attached   the 

desired   physical   device  unit,  not  that  the  unit  was 

attached  by  another  task. 

lE.DNA 

Device  not  attached 

The  physical   device   unit   specified   in  an   lO.DET 

function  was  not  attached  by  the  issuing  task.   This 

code  has  no  bearing  on  the  attachment  status  of  other 

tasks. 

IE. IPC 

Illegal  function 

A  function  code  was  specified  in  an  I/O  request   that 

is  illegal  for  the  UNIBUS  switch  driver. 

(continued  on  next  page) 
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Table  23-3   (Cont.) 
UNIBUS  Switch  Driver  Status  Returns 


Code 


IE. NOD 


lE.OFL 


lE.SPC 


lE.TMO 


Reason 


Insufficient  buffer  space 

Dynamic  storage  space  has  been  depleted,  resulting  in 
insufficient  buffer  space  available  to  allocate 
either  the  I/O  packet  or  the  device  list  buffer. 

Device  off  line 

The  physical  device  unit  associated  with  the  LUN 
specified  in  the  QIO  directive  (the  UNIBUS  switch) 
was  not  on  line,  or  the  CPU  specified  in  the  10. CON 
or  lO.SWI  was  not  on  line. 

Illegal  address  space 

The  buffer  sf-'ified  in  the  10. CON  function  was 
partially  or  totally  outside  the  address  space  of  thn 
issuing  task. 

Time-out  error 

The  time-out  count  expired  during  an  10. DPT  operation 
before  the  target  CPU  requested  the  UNIBUS.  This 
error  code  is  also  returned  when  the  DT03/DT07 
hardware  fails  to  respond  to  a  request  due  to  a 
hardware  failure. 


23.6   FORTRAN  USAGE 

All  of  the  010  functions  described  for  the  UNIBUS  swit.M  driver  can  be 
used  in  FORTRAN  tasks,  except  AST  support  is  not  provided  f .O.ATT 
function  with  an  AST  address  specified).  A  macro  subroutine  can  be 
written  for  the  FORTRAN  task  to  call  that  specifies  the  AST  address. 
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This  appendix  summarizes  legal  I/O  functions  for  all  device  drivers 
described  in  this  manual.  Both  devices  and  functions  are  listed 
alphabetically.  The  meanings  of  the  five  parameters  represented  by 
the  ellipsis  (...)  are  described  in  Section  1.5.1.  The  meanings  of 
the  function-specific  parameters  shown  below  are  discussed  in  the 
appropriate  driver  chapters.  The  user  may  reference  these  functions 
symbolically  by  invoking  the  system  macros  FILIOS  (standard  I/O 
functions)  and  SPCIOS  (special  I/O  functions)  ,  or  by  allowing  them  to 
be  defined  at  task-build  time  from  the  system  object  library. 


A.l   ANA LOG -TO-DIGITAL  CONVERTER  DRIVERS 
lO.KIL,...  Cancel  I/O  requests 

lO.RBC, . . . ,<stadd,size,stcnta>  INITIATE  an  A/D  conversion 


A. 2   CARD  READER  DRIVER 

10. ATT,. 

lO.DET, 


lO.KIL,. 
10. k  B,. 
10. RLE, . 
lO.RVB,. 


. ,<stadd  ,si  ze> 
. ,<stadd ,size> 
. ,<stadd  ,si  ze> 


Attach  device 

Detach  device 

Cancel  I/O  requests 

READ  logical  block  (binary) 

READ  logical  block  (alphanumeric) 

READ  virtual  block  (alphanumeric) 


# 


A. 3   CASSETTE  DRIVER 

10. ATT,. 

lO.DET, . 

10. EOF,. 

lO.KIL,. 

lO.RLB, . . . ,<stadd,si  ze> 


Attach  device 
Detach  device 
Wiite  end-of-file  gap 
Cancel  I/O  requests 
READ  logical  block 
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lO.RVB,. 
lO.RWD, . 
lO.SPB,. 
lO.SPF,. 
lO.WLB,. 
lO.WVD,. 


,<stadd,Aize> 

,<nbs> 
,<nes> 

,<stadd,size> 
,<stadd,size> 
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READ  virtual  block 
Rewind  tape 
SPACE  blocks 
SPACE  files 
WRITE  logical  block 
WRITE  virtual  block 


A. 4   COMMUNICATION  DRIVERS  (MESSAGE-ORIENTED) 


10. ATT, . 
lO.DET,. 
lO.FDX,. 
lO.HDX, . 
lO.INI,,. 

lO.KIL,. 
lO.RLB,. 

lO.RNS,. 
lO.SYN,. 
lO.TRM,. 

lO.WLB,. 
lO.WNS,. 


. ,<stadd ,size> 

. ,<stadd,size> 
. ,<syn> 

. ,<stadd,size> 
. ,<stadd,size> 


Attach  device 

Detach  device 

Set  device  to  full-duplex  mode 

Set  device  to  half-duplex  mode 

Initialize  device  and  set  device 
characteristics 

Cancftl  I/O  requests 

READ  logical  block,  stripping 
sync  characters 

READ  logical  block,  transparent  mode 

SPECIFY  sync  character 

Terminate  communication,  disconnecting 
from  physical  channel 

WRITE  logical  block  with  sync  leader 

WRITE  logical  block,  no  sync  leader 


A. 5   DECTAPE  DRIVER 

lO.RLB, . . . ,<stadd,size, , ,lbn> 


lO.RLV,. 
lO.RVB,. 
lO.WLB,. 
lO.WLV,. 
lO.WVB,. 


.  ,<stadd ,size, , ,lbn> 
. ,<stadd ,size,,,lbn> 
. ,<stadd ,size, , ,lbn> 
. ,<stadd ,size, , ,lbn> 
. ,<stadd ,size, , ,lbn> 


READ  logical  block  (forward) 
READ  logical  block  (reverse) 
READ  virtual  block  (forward) 
WRITE  logical  block  (forward) 
WRITE  logical  block  (reverse) 
WRITE  virtual  block  (forward) 
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A. 6   DECTAPE  II  DRIVER 

10. ATT.. 

lO.DET,. 

lO.KIL,. 

lO.RLB,. 

lO.WLB,. 

lO.WLC,. 

lO.RLC,. 

lO.BLS,. 

lO.DGN,. 


,<stadcl  ,size, ,  ,lbn> 
,<stadd ,size, , ,lbn> 
,<stadd ,size, , ,lbn> 
,<stadd ,size, , ,lbn> 
,<lbn> 


Attach  device 

Detach  device 

Cancel  I/O  requests 

READ  logical  block 

WRITE  logical  block 

WRITE  logical  block  with  check 

READ  logical  bloc'  with  check 

POSITION  tape 

Run  internal  diagnostics 


A. 7   DISK  DRIVER 

10. RLE,. . . ,<stadd,size, ,blkh,blkl> 

lO.RPB, . . . ,<stadd ,size, , ,pbn> 

lO.RVB,. . . ,<stadd,size,,blkh,blkl> 

10. SEC, . . . ,<stadd ,slze ,pbn> 

lO.SMD, . . . ,<density, ,> 

lO.WDD, . . . ,<stadd ,size, , ,pbn> 


lO.WLB,. 
lO.WLC,. 

lO.WPB,. 
lO.WVB,. 


.  ,<stadd,size, ,blkh,blkl> 
.  ,<stadd ,size,,blkh,blkl> 

.  ,<stadd ,size, , ,pbn> 

.  ,<stadd»size, ,blkh,blkl> 


READ  logical  block 

READ  physical  block 

READ  virtual  block 

SENSE  characteristics  (RX02)  only 

SET  media  density  (RX02  only) 

WRITE  physical  block  (with 
deleted  data  mark) 

WRITE  logical  block 

WRITE  logical  block  followed 
by  write  check 

WRITE  physical  block 

WRITE  virtual  block 


A. 8   GRAPHICS  DISPLAY  DRIVER 
10. ATT, 


10. CON,. 
lO.CNT,. 

lO.DET,. 
lO.DIS,. 
lO.KIL,. 
lO.STP,. 


,<stadd,size,lpef ,lpast> 


Attach  device 

CONNECT  to  graphics  device 

Continue     (restart     display- 
processing  unit) 

Detach  device 

Disconnect  from  graphics  device 

Cancel  I/O  requests 

Stop    (halt   display-processinq 
unit) 
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A. 9   INDUSTRIAL  CONTROL  SUBSYSTEMS 

All  I/O  functions  listed  below  apply  to  the  ICS/ICR  subsystem.  The 
five  functions  supported  by  the  DSS/DRSll  subsystem  driver  are  marked 
by  (D). 


lO.CCI,. 

lO.CTI,. 

lO.CTY,. 

lO.DCI,. 

10. DTI, . 

lO.DTY,. 

lO.FLN,. 
lO.ITI, . 
lO.LDI,. 

lO.LKE,. 
lO.LTI,. 
lO.LTY,. 

lO.MLO, . 

lO.MSO,. 

lO.NLK, . 

lO.NLN,. 
10. RAD,. 
lO.RBC,. 
TO. SAO,. 
lO.UDI,. 


,<stadd,sizb,tevf> 


,<stadd ,sizb,tevf ,arv> 


,<stadd  ,sizb,tevf > 


,<mn, ic> 

,<tname, [ ,tevf 1 ,pn,csm> 

,<tname, [ ,tevf ] > 

,<tname , [ ,tevf ] ,cn [ ,arv] > 

,<tname,  [  ,tevf ] > 

,<opn,pp,dp> 

,<opn,dp> 

,<tname> 

,<stadd> 

,<stadd,size,stcnta> 
,<chn,vout> 
,<tnamr!> 


CONNECT  a   buffer   to   digital 
interrupts 

CONNECT  a   buffer   to   counter 
interrupts 

CONNECT  a   buffer   to   terminal 
interrupts 

Disconnect  a  buffer  from  digital 
interrupts 

Disconnect  a  buffer  from  counter 
interrupts 

Disconnect  a  buffer  from  terminal 
interrupts 

Set  controller  off  line 

INITIALIZE  a  counter 

LINK  task  to  digital   interrupts 
(D) 

LINK  task  to  error  interrupts 

LINK  task  to  counter  interrupts 

LINK  task   to   remote   terminal 
interrupts 

OPEN  or  close  bistable  digital 
output  points  (D) 

PULSE  single-shot  digital   output 
points 

UNLINK  a  task  from  all  interrupts 
(D) 

Place  ICR  controller  on  line 

READ  activating  data  (D) 

INITIATE  multiple  A/D  conversions 

PERFORM  analog  output 

UNLINK  a   task   from   digital 
interrupts  (D) 
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lO.UER, . . . ,<tname> 


lO.UTI, . . . ,<tname> 


lO.UTY, . . . ,<tname> 


lO.WLB, . . . ,<staddb,sizb> 


UNLINK   a   task   from    error 
interrupts 

UNLINK   a    task    from   counter 
Interrupts 

UNLINK   a   task    from    terminal 
interrupts 

TRANSMIT  data  to  the   ICR  remote 
terminal 


A. 10   LABORATORV  PERIPHERAL  ACCELERATOR  DRIVER 

lO.CLK, . . . ,<mode,ckcsr ,preset> 

lO.INI,... ,<irbuf ,278.> 

lO.LOD, . . . ,<mbuf ,2048.> 

lO.STA,. . . ,<bufptr,40.> 

lO.STP,. . . ,<userid> 


A. 11   LABORATORY  PERIPHERAL  SYSTEMS  DRIVERS 
10. ADS, 


10. HIS, 

lO.KIL, 
10. LED, 
lO.MDA, 

lO.MDI, 


,<stadd ,size,pnt , 
ticks, bufs,chna> 

,<stadd ,size,pnt , 
ticks, bufs> 


,<int ,num> 

,<stadd ,size,pnt, 
ticks,buf s,chnd> 

,<stadd ,size,pnt , 
ticks, bufs, ma sk> 


lO.MDO, . . . ,<stadd,size,pnt, 
ticks, bufs, mask> 

lO.REL, . . . ,<rel ,pol> 

lO.SDI, . . . ,<mask> 

lO.SDO, . . . ,<mask,data> 

lO.STP, ,<stadd> 


PERFORM  A/D  sampling 

PERFORM  histogram  sampling 

Cancel  I/O  requests 

DISPLAY  number  in  LED  lights 

PERFORM  D/A  output 

PERFORM  digital  input  sampling 

PERFORM  digital  output 

LATCH  output  relay 
READ  digital  input  register 
WRITE  digital  output  register 
STOP  in-progress  request 
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A. 12   LINE  PRINTER  DRIVER 

10. ATT,... 

lO.DET, , . . 

lO.KIL,... 

lO.WLB, . .. ,<stadd,size,vfc> 

lO.WVB, . . . ,<stadd,size,vfc> 


Attach  device 
Detach  device 
Cancel  I/O  requests 
WRITE  logical  block 
WRITE  virtual  block 


A. 13   MAGNETIC  TAPE  DRIVER 

10. ATT,... 

lO.DET, . . . 

10. EOF,... 

lO.KIL,... 

lO.RLB, . . . ,<stadd,size> 

lO.RLV, . . . ,<stadd,size> 

lO.RVB,. . . ,<stadd,siie> 

lO.RWD,. .. 

lO.RWU,... 

10. SEC,. . . 

lO.SMO, . .. ,<cb> 

lO.SPB, ,<nbs> 

lO.SPF, . . . ,<nes> 
lO.STC, . . . ,<cb> 
lO.WLB,. . . ,<stadd,size> 
lO.WVB, . . . ,<stadd,size> 


Attach  device 

Detach  device 

Write  end-of-file  (tape  mark) 

Cancel  I/O  requests 

READ  logical  block 

READ  logical  block  reverse 

READ  virtual  block 

Rewind  tape 

Rewind  and  turn  unit  off  line 

Read  tape  characteristics 

MOUNT  tape  and  set  tape  characteristics 

SPACE  blocks 

SPACE  files 

SET  tape  characteristics 

WRITE  logical  block 

WRITE  virtual  block 


A. 14   PAPER  TAPE  READER/PUNCH  DRIVERS 

10. ATT,...  Attach  device 

lO.DET,...  Detach  device 

lO.KIL,...  Cancel  I/O  Requests 

IO.RLB,...,<stadd,size>       READ  logical  block  (reader  only) 
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lO.RVB, . . . ,<stadd,size> 
lO.WLB, . . . ,<stadd,size> 
lO.WVB,. . . ,<stadd,3ize> 


READ  virtual  block  (reader  only) 
WRITE  logical  block  (punch  only) 
WRITE  virtual  block  (punch  only) 


A. 15   PARALLEL  COMMONICATION  LINK  DRIVERS 

A. 15.1   Transmitter  Driver  Functions 

lO.ATX, . . . ,<stadd,si2e,f lagwd,   ATTEMPT  message  transmission 
id, retries ,retadd> 

10. STC, ... ,<stadd, size, [state]   SET  master  section  characteristics 
[mode] , ,retadd> 


10. SEC, 


Sense  master  section  status 


A. 15.2   Receiver  Driver  Functions 

lO.CRX, . . . ,<tef>  CORRECT  for  reception 

lO.ATF, . . . ,<stadd,size,retadd>   ACCEPT  transfer 

10. RTF,...  Reject  transfer 

lO.DRX,...  Disconnect  from  reception 


A. 16   TERMINAL  DRIVER 


10. ATA,. 

10. ATT, . 
lO.CCO,. 
lO.DET, . 
SF.GMC,. 
10. GTS,. 
lO.HNG, . 
lu.KIL, . 
lO.RAL, . 
10. RLE, . 
lO.RNE, . 


,<ast[ ,parameter2]   ATTACH  device,  specify  unsolici ted- 
[,ast2]>  character  ASTl 

Attach  device 

WRITE  logical  block,  cancel  CTRL/O 

Detach  device 

GET  multiple  characteristics 

GET  terminal  suppct 

HANGUP  remote  line 

Cancel  I/O  requests 
. ,<stadd  ,size [ ,tmo] >  READ  logical  block  and  pass  all  bits^ 
.  ,<.stadd,size[  ,tmo]  >  READ  logical  block! 
.  ,<stadd,size[  ,tmo] >  READ  logical  block  and  do  not  echol 


.  ,<stadd  ,size, vfc> 

. ,<stadd ,size> 
. ,<stadd ,si  ze> 


1.  "ast2",   "parameter2",   and   "tmo"   parameters   are   available   for 
full-duplex  driver  functions  only. 
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lO.RPR, . . . ,<stadd,size, [tmo] ,  READ  after  prompt^ 
pradd  ,prsize,v£c> 

lO.RST, . . . ,<stadd,size( ,tmo] >  READ  with  special  terminators 

lO.RTT, . . . ,<stadd,size, [tmo] ,  READ  logical  block  ended  by  specified 
table>  special  terminator^ 

lO.RVB, . . . ,<stadd,size[ ,tmo] >  READ  virtual  block! 

SF.SMC, . . . ,<stadd,size>       SET  multiple  characteristics 

lO.WAL, . . . ,<stadd,size,vfc>    WRITE  logical  block  and  pass  all  bits 

lO.WBT, . . . ,<stadd,size,vfc>   WRITE  logical  block  and   break   through 

any  ongoing  I/O 

lO.WLB, . . . ,<stadd,size,vfc>    WRITE  logical  block 

lO.WVB, . . . ,<8tadd,8ize,vfc>    WRITE  virtual  block 

Subfunction  bits  for    rminal-dr iver  functions: 

TF.AST         Unsolicited-input-charactet  AST 

TF.BIN         Binary  prompt 

TF.CCO         Cancel  CTRL/0 

TF.ESQ         Recognize  escape  sequences 

TF.NOT         Unsolicited  input  AST  notifications 

TF.RAL         Read,  pass  all  bits 

TF.RCO         Restore  cursor  position^ 

TF.RNE         Read  with  no  echo 

TF.RST         Read  with  special  terminators 

TF.TMO         Read  with  time-out2 

TF.WAL         Write,  pass  all  bits 

TF.WBT         Break-through  write 

TF.XCC         CTRL/C  Starts  a  command  line  interpreter^ 

TF.XOF         Send  XOFF 


1.  "ast2",   "parameter2" ,   and   "tmo"   parameters   are   available   for 
full-duplex  driver  functions  only. 


2.  Full-duplex  driver  only. 
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A.  17   UNIBUS  SWITCH  DRIVER 
lO.ATT, . . . ,< [astl > 
lO.DET, . 


lO.KIL,. 
10. CON,. 
OIOSC  10 
10. DPT,. 

lO.SWI, . 


lO.CSR, . . . 


.  ,<[rcnt] , [cpu] > 
DIS, . . . , 
.,<ttoutl , [port]> 


,<cpu> 


ATTACH  device 

Detach  device 

Cancel  I/O  requests 

CONNECT  UNIBUS  switch 

Disconnect  UNIBUS  switch 

DISCONNECT  UNIBUS  switch  and  connect 
to  specified  CPU  port 

SWITCH  UNIBUS  from  current  CPU  to 
specified  CPU 

Read  UNIBUS  switch  CSR 


A.  18   UNIVEK3AL  DIGITAL  CONTROLLER  DRIVER 


lO.CCI, . . . ,<stadd,sizb,tevf > 


CONNECT  a  buffer  to  contact 
interrupts 


lO.CTI, . . . ,<stadd,Bizb, tevf ,arv>   CONNECT  a  buffer  to  timer 

interrupts 


lO.DCI, . .  . 

10. DTI,... 

lO.ITI, . . . ,<mn,ic> 

lO.KIL,... 

lO.MLO, . . . ,<opn,pp,dp> 

lO.RBC, . . . ,<stadd ,size,stcnta> 


Disconnect  a  buffer  from  contact 
interrupt 

Disconnect  a  buffer  from  timer 
interrupts 

INITIALIZE  a  timer 

Cancel  I/O  requests 

OPEN  or  close  latching  digital 
output  points       . 

INITIATE  multiple  A/D  conversions 


A. 19   VIRTUAL  TERMINAL  DRIVER 

10. ATT,. 
lO.DET,. 
lO.KIL,. 
lO.RLB,. 
lO.RVB,. 
lO.WLB,. 
lO.WVB,. 
lO.STC,. 


,<stadd ,size> 
,<stadd,size> 


Attach  device 
Detach  device 
Cancel  I/O  request 
READ  logical  block 
READ  virtual  block 


,<stadd,size,stat>  WRITE  logical  block 
,<stadd,size,stat>  WRITE  virtual  block 
,<cb,sw2,swl> 


SET  terminal  characteristics  (enable/ 
disable  intermediate  buffering,  or 
return  I/O  completion  status) 
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APPENDIX  B 
I/O  PUMCTION  AND  STATUS  CODES 


This  appendix  lists  the  numeric  codes  for  all  I/O  functions,  directive 
status  returns,  and  I/O  completion  status  returns.  Lists  are 
organized  in  the  following  sequence: 

•  I/O  completion  status  codes 

•  Directive  status  codes 

•  Device-independent  I/O  function  codes 

•  Device-dependent  I/O  function  codes 

Device-dependent  function  codes  are  listed  by  device.  Both  devices 
and  codes  are  organized  in  alphabetical  order. 

For  each  code,  the  symbolic  name  is  listed  in  form  lO.xxx,  lE.xxx,  or 
IS. XXX.  A  brief  description  of  the  error  or  function  is  also 
included.   Both  decimal  and  octal  values  are  provided  for  all  codes. 


B.l   I/O  STATUS  CODES 

This  section  lists  error  and  success  codes  which  can  be  returned  in 
the  I/O  status  block  on  completion  of  an  I/O  function.  The  codes 
below  may  be  referenced  symbolically  by  invoking  the  system  macro 
lOERRS. 


B.1.1   I/O  Status  Error  Codes 

Name  Decimal  Octal                Meaning 

IE. ABO  -15  177761  Operation  aborted 

lE.ALN  -34  177736  File  already  open 

IE. BAD  -01  177777  Bad  parameter 

lE.BBE  -56  177710  Bad  block 

lE.BCC  -66  177676  Block  check  error  or  framing  error 
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Name 

Decimal 

Octal 

lE.BLK 

-20 

177754 

IE. BYT 

-19 

177755 

IE. CNR 

-73 

177667 

IE. CON 

-22 

177752 

lE.DAA 

-08 

177770 

lE.DAO 

-13 

177763 

IE. DMA 

-07 

177771 

lE.DNR 

-03 

177775 

IE. DUN 

-09 

177767 

IE. EOF 

-10 

177766 

IE. EOT 

-62 

177702 

lE.EOV 

-11 

177765 

lE.FHE 

-59 

177705 

lE.FLG 

-89 

177647 

lE.FLN 

-81 

177657 

lE.IEF 

-97 

177637 

lE.IES 

-82 

177656 

lE.IFC 

-2 

177776 

IE. MOD 

-21 

177753 

lE.NLK 

-79 

177661 

lE.NLN 

-37 

177733 

IE. NOD 

-23 

177751 

lE.NST 

-80 

177660 

lE.NTR 

-87 

177651 

lE.OFL 

-65 

177677 

lE.ONP 

-05 

177773 

Meaning 

Illegal  block  number 

Byte-ligned  buffer  specified 

Connection  rejected 

UDC  connect  error 

Device  already  attached 

Data  overrun 

Device  not  attached 

Device  not  ready 

Device  not  attachable 

End-of-file  encountered 

End-of-tape  encountered 

End-of-volume  encountered 

Fatal  hardware  error 

Event  flag  already  specified 

ICS/ICR  controller  already  offline 

Invalid  event  flag 

Invalid  escape  sequence 

Illegal  function 

Invalid  UDC  or  ICS/ICR  module 

Task  not  linked  to  specified 
ICS/ICR  interrupts 

File  not  open 

No  dynamic  memory  available  to 
allocate  a  secondary  control 
block 

Task  specified  in  ICS/ICR  Link  or 
Unlink  request  not  installed 

Task  not  triggered 

Device  off  line 

Illegal  subfunction 


B-2 


I/O  rUNCTIOM  AMD  STATUS  CODES 


Maa* 

Decimal 

Octal 

lE.OVR 

-18 

177756 

IE. PES 

-83 

177655 

lE.PRI 

-16 

177760 

lE.REJ 

-88 

177650 

IE. NOD 

■23 

177751 

lE.RSU 

-17 

177757 

lE.SPC 

-06 

177772 

lE.TMO 

-74 

17766r 

lE.VER 

-04 

177774 

lE.WCK 

-86 

177652 

lE.WLK 

-12 

177764 

Meaning 
Illegal  read  overlav  request 
Partial  escape  sequence 
Privilege  violation 
Transfer  rejected 
No  dynamic  memory  available 
N'.>  isharable  resource  in  use 
Illegal  address  space 
Time-out  error 
Unrecoverable  error 
Write  check  error 
Writt-locked  device 


B.1.2   I/O  Status  Success  Codes 


Decimal 

Octal 

Name 

Bytes 

Word 

IS.CR 

Byte 

0: 

006401 

Byte 

1: 

15 

IS.CC 

Byte 
Byte 

0: 
1: 

001401 

IS. ESC 

Byte 

0: 

015401 

Byte 

1: 

33 

IS. ESQ 

Byte 

0: 

1 

115401 

Byte 

1: 

233 

IS.PND 

+00 

000000 

IS. ROD 

+02 

000002 

IS. sue 

+01 

000001 

IS.TMO 

+02 

000002 

IS.TNC 

+02 

000002 

Meaning 

Successful  completion  with 
carriage  return 

Successful  completion  on 
read  terminated  by  CTRL/C 

Successful  completion 
with  Escape 

Successful  completion  with 
an  escape  sequence 

I/O  request  pending 

Deleted  data  mark  read 

Successful  completion 

Successful  completion  on 
read  terminated  by  time-out 

Successful  transfer  but 
message  truncated  (receiver 
buffer  too  small) 
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B.2   DIRECTIVES  CODES 

This  section  lists  error  and  success  codes  that  can  be  returned  in  the 
directive  status  word  at  symbolic  location  $DSW  when  a  QIO  directive 
is  issued. 


B.2.1  Directive  Error  Codes 


Name 

Decimal 

Octal 

lE.ADP 

-98 

177636 

lE.IEF 

-97 

177637 

lE.ILU 

-96 

177640 

IE. SOP 

-99 

177635 

lE.ULN 

-05 

177773 

lE.UPN 

-OX 

177777 

Meaning 
Invalid  address 
Invalid  event  flag  number 
Invalid  logical  unit  numbor 
Invalid  DIG  number  or  DPB  size 
Unassigned  LUN 
Insufficient  dynamic  storage 


Meaning 
Directive  accepted 


B.2. 2  Directive  Success  Codes 
Name       Decimal      Octal 
IS. sue        +01         000001 

B.3   I/O  FUNCTION  CODES 

This  section  lists  octal  codes  for  all  standard   and  device-dependent 
I/O  functions. 


B.3.1  Standard  I/O  Function  Codes 


Symbolic 
Name 

Word  Equivalent 

Co( 
(High 

lO.ATT 

001400 

3 

lO.DET 

002000 

4 

lO.KIL 

000012 

0 

lO.RLB 

001000 

2 

lO.RVB 

010400 

21 

lO.WLB 

000400 

1 

lO.WVB 

011000 

22 

Subcode 
[Low  Byte)       Meaning 

0  Attach  device 

0  Detach  device 

12  Cancel  I/O  requests 

0  Read  logical  block 

0  Read  virtual  block 

0  Write  logical  block 

0  Write  virtual  block 
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B.3.2  Specific  A/D  Converter  I/O  Function  Codes 

Symbolic  Code      Subcode 

Name    Word  Equivalent  (High  Byte)  (Low  Byte)       Meaning 

lO.RBC        003000         6  0       Initiate  an  A/D 

conversion 


B.3.3  Specific  Card  Reader  I/O  Function  Codes 

Symbolic  Code      Subcode 

Name    Word  Equivalent  (High  Byte)  (Low  Byte)       Meaning 

10. ROB         001200         2  200     Read  logical  block 

(binary) 


B.3.4  Specific  Cassette  I/O  Function  Codes 

Symbolic  Cod       Subcode 

Name    Word  Equivalent  (High  Byte)  (Low  Byte)       Meaning 

lO.EOF         003000  6 


lO.RWD         002400  5 

"B         002420  5 

lO.SPF         002440  5 


B.3.5  Specific  Communication  (Message-Oriented)  I/O  Function  Codes 

Symbolic  Code      Subcode 

Name    Word  Equivalent  (High  Byte)  (Low  Byte)       Meaning 

lO.FDX        003020         6  20      Set  device  to 

full-duplex  mode 

lO.HDX        003010         6  10      Set  device  to 

half-duplex  mode 

lO.INL        002400         5  0       Initialize  device 

and  set  device 
characteristics 

20      Read  logical  block, 
transparent  mode 

40      Specify  sync 
character 

10      Terminate 

communication, 
disconnecting  from 
physical  channel 

lO.WNS        000420         1  20      Write  logical  block 

with  no  sync  leader 
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0 

Write  end-of-file 

gap 

0 

Rewind  tape 

20 

Space  blocks 

40 

Space  files 

lO.RNS 

00.1020 

2 

lO.SYN 

003040 

6 

lO.TRM 

002410 

5 
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B.3.6   Specific  DECtape  I/O  Function  Codes 

Symbolic  Code      Subcode 

Name    Word  Equivalent  (High  Byte)  (Low  Byte) 


lO.RLV 
lO.WLV 


001100 


000500 


2 
1 


100 
100 


Meaning 

Read  logical  block 
(reverse) 

Write  logical  block 
(reverse) 


B.3.7   Specific  DECtape  II  I/O  Function  Codes 

Symbolic  Code      Subcode 

Name    Word  Equivalent  (High  Byte)  (Low  Byte) 


Meaning 


lO.WLC 

420 

1 

20 

Write  logical  block 
with  check 

lO.RLC 

1020 

2 

20 

Read  logical  block 
with  check 

lO.BLS 

4010 

10 

10 

Position  tape 

lO.DGN 

4150 

10 

ISO 

Run  internal 
diagnostics 

B.3.8   Specific  Disk  I/O  Function  Codes 


Symbolic 
Name 

C( 
Word  Equivalent  (Higl 

lO.RPB 

001040          2 

lO.SEC 

002520          5 

lO.SMD 

002500          5 

lO.WDD 

001140          1 

lO.WLC 

001020          1 

lO.WPB 


000440 


t   Byte)       Meaning 

40      Read  physical  block 
(RXOl,  RLOl,  RL02 
only) 

120     Sense 

characteristics 
(RX02  only) 

100     Set  media  density 
(RX02  only) 

140     Write  physical  block 
with  deleted  data 
mark  (RX02  only) 

20      Write  logical  block 
followed  by  write 
check  (all  except 
RX01«  RX02) 

40      Write  physical  block 
(RXOl,  RX0  2,  RLOl, 
RL02  only) 


B-6 


I/O  PUWCTION  AND  STATUS  CODES 


B.3.9  Specific  Graphics  Display  I/O  Function  Codas 


Symbolic 
Name 

10. CON 


lO.CNT 
lO.DIS 

lO.STP 


Code      Subcode 
Word  Equivalent  (High  Byte)  (Low  Byte) 


015400 

017000 
016000 

016400 


33 

36 
34 

35 


Meaning 


00 

Connect  to  graphics 

device 

00 

Continue  DPU 

00 

Disconnect  from 

graphics  device 

00 

Stop  DPU 

B,3.10  Specific  ICS/ICR,  DSS/DR  I/O  Function  Codes 


^ 


Symbolic 

Name    Word  Equivalent 


lO.CCI 


lO.LTY 


014000 


lO.CTI 

015400 

33 

lO.CTY 

0034G0 

7 

lO.DCI 

014^00 

31 

010000 


Code      Subcode 
(High  Byte)  (Low  Byte) 

30  0 


10. DTI 

016000 

34 

lO.DTY 

006400 

15 

lO.PLN 

012400 

25 

lO.ITI 

017000 

36 

lO.LDI 

007000 

16 

lO.LKE 

012000 

24 

lO.LTI 

007400 

17 

20 


0 

0 


Meaning 

Connect  a  buffer  to 
digital  interrupt 
input 

Connect  a  counter 

Connect  a  remote 
terminal 

Disconnect  a  buffer 
from  digital 
interrupt  input 

Disconnect  a  buffer 
from  counter  input 

Disconnect  a  buffer 
from  terminal  input 

Place  selected  unit 
off  line 

Initialfze  a  counter 

Link  a  task  to 
digital  interrupts 

Link  a  task  to  error 
interrupts 

Link  a  task  to 
counter  interrupts 

Link  a  task  to 
terminal  interrupts 
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Symbolic 
Name 

lO.MLO 


lO.MSO 


lO.NLK 


lO.ONL 


10. RAD 


lO.RBC 


10. SAO 


Code      Subcode 
Word  Equivalent  (High  Byte)  (Low  Byte) 


006000 

005000 

011400 

017400 
010400 
003000 
004000 


14 


12 


23 


37 


21 


10 


lO.UDI 

011410 

23 

lO.UER 

011440 

23 

lO.UTI 

011420 

23 

lO.UTY 

011430 

23 

lO.WLB 

000400 

1 

0 
0 
0 
0 

10 
40 
20 
30 
0 


Meaning 

Open  or  close 
bistable  digital 
output  points 

Pulse  single-shot 
digital  output 
points 

Unlink  a  task  from 
all  unsolicited 
interrupts 

Place  selected  unit 
on  line 

Read  task  activation 
data 

Initiate  multiple 
A/D  conversions 

Perform  analog 
output  to  specified 
channel 

Unlink  a  task  from 
digital  interrupts 

Unlink  a  task  from 
error  interrupts 

Unlink  a  task  from 
counter  interrupts 

Unlink  a  task  from 
terminal  interrupts 

Output  to  remote 
terminal 


B.3.11   Specific  LPAll-K  I/O  Function  Codes 


Symbolic 
Name 

Word  Equivalent 

Co 
(High 

lO.CLK 

015000 

32 

10. INI 

014400 

31 

lO.LOD 

014000 

30 

lO.STA 

015400 

33 

lO.STP 

016400 

35 

Subcode 
(Low  Bytt 

0 

0 

0 

1 

0 


Meaning 

Start  clock 
Initialize  LPAll-K 
Load  microcode 
Start  transfer 
Stop  request 


• 
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B.3.12  Spacific  LPS  I/O  Function  Codes 
Syabolic  Code      Subcode 


Hue 

Word  Equivalent 

(High 

10. ADS 

014000 

30 

10. HIS 

015000 

32 

lO.LED 

012000 

24 

lO.NDA 

016000 

34 

lO.MDI 

014400 

31 

lO.MDO 

015400 

33 

lO.REL 

013400 

27 

lO.SDI 

013000 

26 

lO.SOO 

012400 

25 

lO.STP 

016400 

35 

Meaning 


0 

Initialize  A/D 
sampling 

0 

Initialize  histogram 
sampling 

0 

Display  number  in 
LED  lights 

0 

Initialize  D/A 
output 

0 

Initialize  digital 
input  sampling 

0 

Initialize  digital 
output 

0 

Latch  output  relay 

0 

Read  digital  input 
register 

0 

Write  digital  output 
register 

0 

Stop  in-progress 

request 


B.3.13   Specific  Magtape  I/O  Function  Codes 


Symbolic 
Name 

Nord  Equivalent  (H 

C 

lig 

10. EOF 

003000 

6 

lO.RLV 

001100 

2 

lO.RWD 

002400 

5 

lO.RWU 

002540 

5 

10. SEC 

002520 

5 

lO.SMO 


002560 


lO.SPB 

002420 

S 

lO.SPF 

002440 

5 

lO.STC 

002500 

5 

Meaning 


0 

Write  end-of-file 

gap 

100 

Read  logical  block 

(reverse) 

0 

Rewind  tape 

140 

Rewind  and  unload 

120 

Sense 

characteristics 

160     Mount  and  set 

characteristics 

20      Space  blocks 

40      Space  files 

100     Set  characteristics 
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B.3.14   Specific  Parallel  Coaaani cat ions  Link  I/O  Function  Codas 
B.3.14.I  Transaittar  Dtivas  Functions  - 


Syabolic 
Haa« 

10. ATX 
lO.STC 
10. SEC 


Coda 


Subcode 


Word  Equivalent  (High  Byte)  (Low  Byte) 
000400         I  0 


002500 
002520 


S 

s 


100 
120 


Meaning 

Attempt  message 
transmission 

Set  master  section 
characteristics 

Sense  master  section 
status 


B. 3. 14.2  Receiver  Driver  Functions  - 


Syabolic 
Naae 

lO.CRX 


lO.ATF 
10. RTF 
lO.DRX 


Code      Subcode 
Nord  Equivalent  (High  Byte)  (Low  Byte) 


014400 

001000 
015400 
001500 


31 

2 

33 

32 


0 
0 
0 


Meaning 

Conneect  for 
reception 

Accept  transfer 

Reject  transfer 

Disconnect  from 
reception 


B.3.15  B.3.15  Specific  Terainal  I/O  Function  Codes 


Syabolic 
Naae 

10. ATA 


Code      Subcode 
Nord  Equivalent  (High  Byte)  (Low  Byte) 


001410 


lO.CCO 

000440 

1 

SP.GMC 

002560 

5 

10. GTS 

002400 

5 

lO.HNG 

003000 

6 

lO.RAL 

001010 

2 

10 

40 

160 

00 

0 

10 


Meaning 

Attach  device, 
specify 

unsol i cited- input- 
character  AST 

Write  logical  block 
and  cancel  CTRL/O 

Get  multiple 
characteristics 

Get  terminal  support 

HANGUP  remote  line 

Read  logical  block 
and  pass  all  bits 
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Syabolic 
Name 

lO.RNE 

ID. RPR 

lO.RST 

lO.RTT 


Code      Subcode 
Word  Equivalent  (High  Byte)  (Low  Byte) 


001020 
004400 
001001 

005001 


2 

11 

2 

12 


SF.SMC 

002440 

5 

lO.WAL 

000410 

1 

lO.WBT 

000500 

1 

20 
00 
1 


40 

10 

100 


Meaning 

Read  with  no  echo 

Read  after  prompt 

Read  with  special 
terminators 

Read  logical  block 
ended  by  specified 
special  terminator 
(Full-duplex  driver 
only) 

Set  multiple 
characteristics 

Write  logical  block 
nd  pass  all  bits 

Write  logical  block 
and  break  through 
on-going  I/O 


Subfunction  Bits: 


With  lO.RLB,  10. RPR! 

TF.RST 
TF.BIM 
TF.RAL 
TF.RNE 
TF.XOF 
TF.TMO 


1 

2 

10 

20 

100 

200 


With  lO.WLB: 


TF.WAL 
TF.CCO 
TF.WBT 


With  10. ATT: 


10 

40 

100 


TF.AST 
TF.ESQ 


10 
20 
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10. DTI 

016000 

34 

lO.ITI 

017000 

36 

lO.MLO 

006000 

14 

I/O  FUNCTION  AND  STATUS  CODES 

B.3.16  Specific  UDC  I/O  Function  Codes 

Symbolic  Code      Subcode 

Name    Word  Equivalent  (High  Byte)  (Low  Byte)       Meaning 

lO.CCI        014000         30  0       Connect  a  buffer  to 

contact  interrupt 
digital  input 

lO.CTI        015400         33  0       Connect  a  timer 

lO.DCI        014400         31  0       Disconnect  a  buffer 

from  contact 
interrupt  digital 
input 

0       Disconnect  a  timer 

0       Initialize  a  timer 

0       Open  or  close 

latching  digital 
output  points 

lO.RBC        003000         6  0       Initiate  multiple 

A/D  conversions 


B.3.17   Specific  UNIBUS  Switch  I/O  Function  Codes 

Symbolic  Code      Subcode 

Name    Word  Equivalent  (High  Byte)  (Low  Byte)       Meaning 

10. CON        15400  33  0       Connect  UNIBUS 

switch 

lO.DIS        16000  34  0       Disconnect  UNIBUS 

switch 

10. DPT        16010  34  10      Disconnect  UNIBUS 

switch  and  co-  ect 
to  specified  Lr^U 
port 

lO.SWI        16400  35  0       Swit.-h  UNIBUS  from 

currer.t  CPU  to 
specified  CPU 

lO.CSR        15000  32  0       Read  UNIBUS  switch 

CSR 


B.3.18   Specific  Virtual  Terminal  I/O  Function  Codes 

Symbolic  Code      Subcode 

Name    Word  Equivalent  (High  Byte)  (Low  Byte)       Meaning 

lO.STC        002500         5  100     Set  terminal 

characteristics 


e 
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This  appendix  describes  the  010  level  interface  to  the  file  processors 
(ACPs) .  These  include  FllACP  for  Files-11  disks  and  MTAACP  for  ANSI 
magnetic  tape. 

FllACP  supports  the  following  functions: 

lO.CRE  Create  file 

10. DEL  Delete  file 

lO.ACR  Access  file  for  read  only 

lO.ACW  Access  file  for  read/write 

10. ACE  Access  file  for  read/write/extend 

lO.DAC  Deaccess  file 

10. EXT  Extend  file 

10. RAT  Read  file  attributes 

10. WAT  Write  file  attributes 

lO.FNA  Find  file  name  in  directory 

lO.RNA  Remove  file  name  from  directory 

lO.ENA  Enter  file  name  in  directory 

lO.ULK  Unlock  block 

MTAACP  supports  the  following  functions: 

lO.FNA  Find  fila  by  name 

lO.ENA  Enter  name  in  directory  (s  no-op) 

lO.ACR  Access  for  read  only 

lO.ACW  Access  for  read/write 

10. ACE  Access  for  read/write/extend 

lO.DAC  Deaccess  file 

lO.RVB  Read  virtual  block 

lO.WVB  Write  virtual  block 

10. EXT  Extend  file 

lO.CRE  Create  file 

10. RAT  Read  attributes 

lO.APC  ACP  control 

lO.APV  Privileged  ACP  control 


C.l   QIO  PARAMETER  LIST  FORMAT 

The  device-independent  part  of  a  file  processing  QIO  parameter  list  is 
identical  to  all  other  QIO  parameter  lists.  The  general  QIO  parameter 
lists  is  described  in  detail  in  Section  l.fi  of  this  manual.  The  file 
processor  QIOs  require  the  following  six  additional  words  in  the 
parameter  lists: 

t'arameter  Word  1         Address  of  a  3-wor<i  block  containing  the 

filfc  identifid;. 
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parameter  WorJ    2 

Parameter  Mbrds   3  fc   4 

Parameter  Word   5 

parameter  word   6  ■ 


Address  of  the   attribute   list 

Size   and   extend   control    information 

Window     size      information        and        access 
control 

Address  of   the   file  name  block 


•  •  NOTE 

The  RSX-llM/M-PLUS  Executive  treats  File 
Identifier  Blocks,  filename  blocks,  and 
attribute  list  entries  as  read/write 
data.  For  this  reason,  they  may  not  be 
used  in  read-only  code  segments  or 
libraries. 


C.1.1  Pile  Identification  Block 

The  File  Identification  Block  is  a  1-word  block  containing  the  file 
number  and  the  file  sequence  number.  The  format  of  the  File 
Identification  Block  is  shotm  in  Figure  C-1. 


File  Number 

File 

Sequence 

Number 

Reserved 

Figure  C-1   File  Identification  Block 


FllACP  uses  the  file  number  as  an  index  to  the  file  header  in  the 
index  file.  Each  time  a  header  block  is  used  for  a  new  file,  the  file 
sequence  number  is  incremented.  This  insures  that  the  file  header  is 
always  unique.  The  third  trord  is  not  currently  used  but  is  reserved 
for  the  future. 


C.1.2  The  Attribute  Liat 

The  file  attribute  list  controls  FllACP  reads  or  writes.  File 
attributes  are  fields  in  the  file  header.  These  fields  are  described 
in  detail  in  Appendix  F  of  the  lAS/RSX  I/O  Operations  Reference 
Manual . 

The  attribute  list  contains  a  variable  number  of  entries  terminated  by 
an  all-0  byte.  The  maximum  number  of  entries  in  the  attribute  list  is 
six . 

An  entry  in  the  attribute  list  has  the  following  format: 

.BYTE   <Attribute  type> ,  Attribute  size 
.WORD  Pointer  to  the  attribute  buffer 


• 
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C. 1.2.1  Thtt  Attribute  Typ«  -  This  field  identifies  the  individual 
attribute  to  be  read  or  wiitten.  The  sign  of  the  attribute  type  code 
deterinirt;:f  whether  the  transfer  is  a  read  or  write  operation.  If  the 
type  code  is  negative,  the  ACP  reads  the  attribute  into  the  buffer. 
If  the  type  code  is  positive,  the  ACP  writes  the  attribute  to  the  file 
header.  Note  that  the  sign  of  the  type  code  must  agree  witn  the 
direction  implied  by  the  operation.  For  example,  if  the  type  code  is 
positive,  the  operation  must  be  an  10. WAT  or  lO.DAC. 

The  attribute  type  is  one  of  the  following: 

•      File  owner    (H.FOWN) 

The  file  owner  UIC  is  a  binary  word.  The  low  byte  is  the 
owner   number   and    the   high  byte    is   the  group  number. 

e      File   protection    (H.FPRO) 

The  file  protection  word  is  a  bit  mask  with  the  following 
format : 

Each  of   the    fields  contains   four   bits,   as   follows: 

Bit  1  Read   Access 

Bit  2  Write   Access 

Bit  "1  Extend    Access 

Bit  A  Delete   Access 

e      File  characteristics    (H.UCHA) 

The  following  user  characteristics  are  currently  contained  in 
the    1-byte    H.UCHA   field: 

DC. CON   *   200        Logically  contiguous    file 
UC.DLK   »   100        File    improperly  closed 

e      Record    I/O  Area    (U.UFAT) 

This  field  contains  a  copy  of  the  first  seven^  words  of  the 
file  descriptor  block.  See  Appendix  A  of  the  lAS/RSX  I/O 
Operations  Reference   Manual    for   a  description  of   the    FDB. 

e   File  name  (I.FNAM) 

The  file  name  is  stored  as  nine  Radix-50  characters.  the 
fourth  word  of  this  block  contains  the  file  type  and  the  fifth 
word  contains  the  version  number. 

e   File  type  (I.FTYP) 

The  file  type  is  stored  as  three  Radix-50  characters. 

e   Version  number  (I.FVER) 

The  version  number  is  stored  as  a  binary  number. 

e   Expiration  date  (I.EXDT) 
Creation  date  (I.CRDT) 
Revision  date  (I.RVDT) 

The  expiration  date  is  currently  unused.  When  the  file  is 
created,  the  ACP  initializes  the  creation  date  to  the  current 
date  and  time.  It  initializes  the  expiration  and  revision 
dates  to  0.  The  ACP  sets  the  revision  date  to  the  current 
date  and  time  each  time  the  file  is  deaccessed. 


1.  RMS  uses  32  bytes.   The  first  seven  are  compatible  with   FCS   for 
sequential  files. 
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Statistics  block 

This  block  is  described  in   Appendix   H  of   the   lAS/RSX   I/O 

Operations  Reference  Manual . 

Read  entire  file  header 

This  buffer  is  assumed  to  be  1000   blocks   long.    You  cannot 

write  this  attribute. 


Revision  number  (I.RVNO) 

The  ACP  sets  the  revision  number  to  0,  and  increments  it  every 

time  the  file  is  deaccessed. 

Placement  Control 


C.1.2.2  Attribute  Site  -  This  vrord  specifies  the  number  of  bytes  of 
the  attribute  to  be  transferred.  Legal  values  are  from  1  to  the 
maximum  size  of  the  particular  attribute.  Table  C-1  shows  the  maximum 
size  for  each  attribute  type. 


Table  C-1 
Maximum  Size  for  Each  File  Attribute 


Maximum 

Attribute 

Attribute 

Attribute  Size 

Type  Code 

Type 

In  Octal  Bytes 

1 

File  owner 

6 

2 

Protection 

4 

3 

File  characteristics 

2 

4 

Record  I/O  area 

40 

5 

File  name, type, version  number 

12 

« 

File  type 

4 

7 

Version  number 

2 

10 

Expiration  date 

7 

11 

Statistics  block 

12 

12 

Entire  file  header 

0 

13 

Block  Size  (magtape  only) 

— 

15 

Revision  number  and 

creation/ revision/ex pi  rat  ion  dates 

43 

16 

Placement  control 

1« 
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C.1.2.3  Attribute  Buffer  Address  -  The  attribute  Buffer  Address  field 
contains  the  address  of  the  buffer  in  the  user's  task  space  to  or  from 
which  the  attribute  is  to  be  transferred. 


C.I. 3  Sice  and  Extend  Control 

These  two  parameters  specify  how  many  blocks  the  file  processor 
allocated  to  a  new  file  or  adds  to  an  existing  file.  These  parameters 
also  control  the  type  of  block  allocation. 

The  format  is  as  follows: 

.BYTE  <High  8  bits  of  size>,  <extend  control> 
.WORD   <Low  16  bits  of  size> 

The  size  field  specifies  the  number  of  blocks  to  be  allocated  to  a 
file  on  lO.CRE  and  10. EXT  operations,  and  the  final  file  size  on 
10. DEL  operations. 

The  extend  control  field  controls  the  manner  in  which  an  extend 
operation  is  to  be  done.   The  following  bits  are  defined: 

EX.AC1>1  The  extend  size  is  to  be  added  as  a  contiguous 
block. 

EX.AC2«2  Extend  by  the  largest  available  contiguous  piece  up 
to  the  specified  size. 

EX.FC0<:4     The  file  must  end  up  contiguous. 

EX.ADF'IO  Use  the  default  rather  than  the  specified  size.  The 
default  extend  size  is  the  size  that  was  specified 
when  the  volume  was  mounted. 

EX.ALL>20    Placement  control  (see  Section  C.2). 

EX.ENA>200    Enable  extend. 


C.1.4  Window  Size  and  Access  Control 

This  parameter  specifies  the  window  size  and  access  control 
information  in  the  following  format: 

.BYTE   <win(Iow  size>,  <access  control> 

This  word  is  only  processed  if  the  high  bit  of  the  access  control  byte 
(AC.ENB)  is  set. 

Window  size  is  the  number  of  mapping  entries.  Specifying  a  negative 
window  size  minimizes  window  turns.  If  this  byte  is  zero,  the  file 
processor  uses  the  volume  default.  The  size  of  the  window  allocated 
in  the  dynamic  storage  region  is  6  times  the  number  of  mapping  entries 
(each  mapping  entry  is  3  words) ,  plus  10  bytes  for  the  window  control 
block. 
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On  RSX-IIM-PLUS  systems  with  secondary  pool  support,  the  m.ipping 
entries  are  allocated  in  secondary  pool.  The  window  control  block  and 
a  pointer  to  secondary  pool  are  located  in  primary  pool. 

The  following  access  control  bits  are  defined: 

AC.LCK'l      Lock  out  further  accesses  for  Write  or  Extend 

AC.OLK'2      Enable  Deaccess  lock 

The  deaccess  lock  sets  the  lock  bit  in  the  file  header 
if  the  file  is  deaccessed  as  the  result  of  a  task 
exit  without  explicitly  deaccessing  the  file.  The 
lock  bit  is  set  by  the  executive.  The  lock  bit  is  not 
set  when  the  system  crashes. 

AC.LKL>4      Enable  block  locking 

AC.EXL-10     Enable  explicit  block  unlocking 

AC.ENB-200    Enable  Access 

AC.RWD'IO     Rewind  the  volume  (labeled  and  unlabeled  magtape  only) 

AC.UPD-100    Update  mode  (labeled  magtape  only) 

AC.POS«20     Do  Not   Position   to   end-of-volume   (labeled   magtape 
only) 

AC.WCK-40     Initiate  driver  wr i te-checking 

MOTE 

Both  AC.LKL  and  AC.EXL  must  be  set  if 
you  want  block  locking.  If  you  do  not 
want  block  locking,  both  bits  must  be 
clear.  Any  other  combination  is  an 
error  . 


C.1.5  Pile  Mane  Block  Pointer 

This  word  contains  the  address  of  a  15-word  block  in  the  issuing 
task's  space.  This  block  is  called  the  file  name  block.  The  file 
name  block  is  described  in  detail  in  Appendix  B  of  the  lAS/RSX  I/O 
Operations  Reference  Manual . 

The  fields  of  the  file  name  block  that  are  particularly  important  in 
file-processing  operations  are: 

•  Directory  identification  (N.DID) 

This  field  is  required  for  all  disk  operations.  It  specifies 
the  directory  to  which  th<a  operation  applies.  This  field  is 
not  used  for  tape  operations. 

•  File  identification  (N.PID) 

This  field  is  required  as  input  for  enter  operations.  This 
field  is  returned  as  output  by  find  and  remove  operations. 

•  Pile  name  (N.PNAM),  type  (N.FTYP),  and  version  number  (N.PVER) 
These  fields  are  required  as  input  to  enter,  find,  and  remove 
operations.  For  find  and  remove  operations,  the  file 
processor  locates  the  appropriate  entry  by  matching  the 
information  in  these  fields  with  the  directory  entries. 

•  Status  word  (N.STAT) 

•  Wildcard  context  (N.NEXT) 

This  field  is  required  as  input  for  wildcard   operations.  It 

specifies   the   point   at   which   to  resume  processing.   It  is 

updated  for  the  next  operation.  It  must  initially  be  set  to 
0. 
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C.2   PLACBMINT  CONTROL 

Th«  placement  control  attribute  list  entry  controls  the  placement  of  a 
file  in  a  particular  place  on  the  disk.  You  can  specify  either  exact 
or  approximate  placement  on  lO.CRE  and  10. EXT  operatK.ts. 

The  placement  control  entry  must  be  the  first  entry  in  the  attribute 
list. 

The  format  of  the  placement  control  attribute  list  entry  is  as 
follows: 

.BYTE   placement  control, 0 
.WORD   high-order  bits  of  VBN  or  LBN 
.WORK   low-order  bits  of  VBN  or  LBN 

.BLKW  4       ;  Buffer  to  receive  starting  and  ending  LBN  if 
AL.LBN  is  set. 

The  following  bits  are  defined  for  the  placement  control  field: 

AL.VBN*1     Set  if  block  specified  is   a   VBN;    otherwise,   the 

block  is  the  LBN 
AL.APX-2     Set  if  you  want  approximate  placement; 

otherwise,  placement  is  exact 
AL.LBNs4      Set  if  you  want  starting  and  ending  LBN  information 


C.3   BLOCK  LOCKING 

Block  locking  only  occurs  when  the  user  accesses  a  file  with  AC.LKL 
and  AC.EXL  set  in  the  access  control  byte  of  the  parameter  list.  Any 
read  or  write  operation  causes  a  check  to  see  if  ^he  block  is  locked. 

A  write  access  locks  a  block  for  exclusive  access.  A  write  operation 
can  only  access  a  block  that  is  not  locked  by  any  accessor.  The  only 
exception  to  this  is  an  exact  match  with  a  previous  lock  owned  by  the 
same  accessor. 

A  read  access  locks  a  block  for  shared  access.  A  read  operation  can 
access  any  block  Jocked  for  shared  access. 

The  user  must  unlock  a  block  with  an  explicit  unlock  request,  lO.ULK. 
lO.ULK  may  be  used  to  unlock  one  or  all  blocks. 

If  all  accessors  to  a  file  have  not  requested  block  locking,  the  AGP 
retnrns  an  error  (see  Table  C-2) . 

When  the  file  is  deaccessed,  all  locks  owned  by  the  accessor  are 
released. 

Each  active  lock  requires  eight  bytes  from  the  dynamic  storage  region. 
This  storage  is  deallocated  when  the  file  is  deaccessed. 


C.4   SONMART  OP  PllACP  FUNCTIONS 

The  following  is  a  summary  of  the  functions  implemented  in  FllACP.  A 
list  of  accepted  parameters  follows  each  function.  Ail  parameters  are 
required  unless  specified  as  optional.  Parameters  other  than  those 
listed  are  illegal  for  that  functijn  and  must  be  0. 
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lO.CRE  Great*  file 


lO.DEL 


lO.ACR 
lO.ACH 
10. ACE 


lO.DAC 


10. EXT 


10. RAT 


lO.FNA 
lO.RNA 


•  2 


The  file  identifier  block  is  filled  in  with  the   file 
identifier,  and  sequence  number  of  the  created  file. 


Write  Attribute   and/or 
(optional) 


Placement   Control 


list 


f3  fc  #4  Extend  Control  (optional) 

The  amount  allocated  to  the  file  is  returned   in   the 
high  byte  of  lOST(l)  plus  I0ST(2). 

#5      May  be  nonzero  but  must  be  disabled 

Delete  or  truncate  file 

#1      Optional  if  the  file  is  accessed 

#3  fc  14  Size  to  truncate  the  file  to.  If  not  enabled,  the 
file  is  deleted.  If  enabled,  the  remaining  31  bits 
specify  the  size  the  file  is  to  be  after  truncation. 
The  change  in  file  allocation  is  returned  in  the  high 
byte  of  lOST(l)  plus  I0ST(2) .  This  amount  will  be 
zero  or  negative. 

Access  file  for  read  only 

Access  file  for  read/write 

Access  file  for  read/write/extend 
II      File  identifier  pointer 
#2      Read  attributes  control  (optional) 
tS      Access  control  must  be  enabled 

Deaccess  f  i le 
91      File  identifier  pointer  (optional) 
#2      Write  attributes  control  list 
#5      Nay  be  nonzero  but  must  be  disabled 

Extend  file 

11  Optional  if  file  is  accessed 

12  Placement  control  attribute  list  (optional) 

13  it  14  Extend  control 

The  amount  allocated  to  the  file  is  returned   in   the 
high  byte  of  lOST(l)  plus  I0ST(2). 

Read  attributes 

11  Optional  if  file  is  accessed 

12  Read  attributes  control  list 
Find  name  in  directory 
Remove  name  from  directory 
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lO.ENA  Enter  name  in  directory 

IS      May  be  nonzero  but  must  be  disabled 
*   ■§$  File  name  block  pointer 


>  . 
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lO.ULK  Unlock  block 

#2  0  or  count  of  blocks  to  unlock 

14  &  15  Starting  VBN  to  unlock  or  0  to  unlock  all  blocks. 

lO.RVB  Read  virtual  block 

lO.WVB   \  Write  virtual  block 

#1  User  buffer 

»       ,#8  Buffer  length 

14  &  »5  VBN 

C.5   SOHMARY  OF  MTAACP  FUNCTIONS 

The  following  is  a  summary  of  the  functions  implemented  in  MTAACP.  A 
list  of  accepted  parameters  follows  each  function.  All  parameters  arf> 
required  unless  specified  as  optional.  Parameters  other  than  those 
listed  are  illegal  for  that  function  and  must  be  0. 

lO.FNA  Find  file  by  name 

#5  AC.RWD  set  in  the  access  control  byte  indicates 
that  the  volume  is  to  be  rewound  prior  to  the 
search. 

#6      Pointer  to  file  name  block. 

The  following  fields  are  used  as  input: 

N.FNAM 
N.FTYP 
N.FVER 
N.STAT 

The  following  fields  are  returned  by  MTAACP: 

N.FID 

N.FNAM 

N.FTYP 

N.FVER 

N.STAT 

lO.ENA   Enter  name  in  directory  —  a  no-op  for  magnetic  tape 

lO.ACR  Access  for  read  only 

#1  File  identifier  pointer.  Used  to  position  a 
tape  by  file  identifier. 

#2      Read  attribute  list  (optional) 

#S      Ignored 

lO.ACW  Access  for  read/write 

This  function  will  be  rejected  with   the  error 
code  lE.PRI.   (Extend  access  is  required.) 
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10. ACE  Access  for  read/write/extend 

ffl  File  identifier  pointer.  Used  to  position  tape 
by  file  identil'ier. 

#2      Read  attribute  list  (optional) 

#9  AC.UPD  (update  mode).  If  AC.UPD  is  set,  the 
tape  will  be  positioned  to  overwrite  the  file 
and  all  files  beyond  the  current  file  will  be 
lost.  If  AC.UPD  is  not  set,  the  tape  will  be 
positioned  for  append.  If  the  file  is  not  the 
last  file,  MTAACP  returns  the  error  code 
IE.IS(}. 

lO.DAC  Deaccess  file 

#1      File  identifier  pointer  is  ignored. 

fS  AC.RWD  set  indicates  that  the  volume  is  to  be 
rewound  after  the  file  is  closed. 

lO.RVB   Read  virtual  block 

#1      Buffer  address 

#2  Buffer  size.  The  buffer  size  must  be  greater 
than  18  bytes  and  less  than  the  declared  block 
length  for  the  entire  file. 

#4      High  VBN 

#5      Low  VBN 

The  virtual  block  number  must  be  either  zero  or  exactly  one 
greater  than  the  previous  block  number. 

lO.CRE  Create  File 

tl  File  identifier  pointer.  The  file  sequence  and 
section  number  will  be  returned  to  the  user's 
file  identifer  block. 

#2  Attribute  list  pointer.  Used  to  write  the 
attributes  for  the  newly  created  file. 
Attribute  type  code  must  be  positive. 

#5  If  AC.RWD  is  set,  the  volume  will  be  positioned 
at  the  beginning  and  will  overwrite  the  first 
file.  This  effectively  reinitializes  the 
volume. 

If  AC.RWD  is  not  set  and  AC. PCS  is  set,  the 
volume  set  will  be  positioned  to  the  next  file 
position  beyond  the  current  file  and  will 
overwrite  that  file.  All  files  beyond  that  on 
the  volume  will  be  destroyed. 

If  neither  AC.RWD  nor  AC. PCS  is  set,  the  volume 
set  will  be  positioned  at  its  end  and  the  new 
file  will  be  appended  to  the  set. 

For  unlabeled  tapes,  MTAACP  only  checks  AC.RWD. 

#C      Filename  block  pointer. 
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10. RAT  Read  Attributes 

#1      Pile  identifier  pointer.   Used  to  position   the 
tape  by  the  file  identifier. 

t2      Attribute  list  pointer  (see  Section  C.1.2) 

.  The   following  attribute   list   entries   are 
meaningful  for  magnetic  tape: 

1,2    UIC 

1.4  UIC  and  protection 

1.5  UIC  protection,  and  characteristics 

2.2  Protection 

2.3  Protection  and  characteristics 

3.1  Characteristics 
4,32   User  file  attributes 
5,f>    File  name 

5,8  File  name  and  type 

5,10  File  name  and  type 

6.2  File  type 

6.4  File  type  and  version  number 
7,2  Version  number 

8,7  Expiration  date 

-9,10  Statistics  block  (read  only) 

-10,0  Entire  header  (read  only) 

11,2  Block  size 

lO.APC  ACP  Control 

13      One  of   the   following   user   control   function 
codes: 

1  Rewind  volume  set. 

2  Position  to  end  of  volume  set. 

3  Close  current  volume  and  continue 
processing  the  next  section  of  the  same 
file  on  the  next  volume  of  the  volume 
set. 

4  Space  physical  records  in  currently 
accessed  file. 

5  Get  ACP  characteristics. 

6  Rewind  current  file. 

lO.APV  Privileged  ACP  Control 

This  function  is  used  only  by  the  MOUNT  and   DISMOUNT 

commands.    This  interface   is  subject  to  change  and, 

therefore,  will  not  be  documented   until   a   future 
release. 


C.6   HOW  TO  USE  THE  ACP  QIOS  • 

Although  the  operations  described  in  this  appendix  are  normally 
performed  by  the  file-access  methods  (RMS  and  FCS) ,  your  application 
may  issue  the  ACP  QIOs.  The  required  parameters  for  each  010  are 
described  above.  The  necessary  steps  for  common  operations  are 
described  below. 


NOTE 

The  file  identifier  is  the  only  way  to 
refer  to  a  file. 


C-11 


010  INTERFACE  TO  THE  ACPS 

C.fi.l  Creating  a  Pile 

To  create  a  file: 

e   Use  lO.CRE  to  create  it. 

•   Enter  it   in   the  Master   File   Directory   (MFD)   or  a   user 
directory  with  lO.ENA. 


C.«.2  Opening  a  Pile 
To  open  a  file: 

•  Use  lO.FNA  to  find  the  File  Identifier  of  the  directory  in  the 
MFD. 

•  Use  lO.FNA  to  find  the  File  Identifier  of   the   file   in   the 
directory. 

•  Access  the  file  with  lO.ACR,  lO.ACW,  or  10. ACE. 


C.ft.B  Closing  a  Pile 
To  close  a  file: 

•  Deaccess  the  file  with  lO.DAC. 

C.^.4   Extending  a  Pile 
To  extend  a  file: 

•  Use  lO.FNA  to  find  the  file  Identifier   if   the   file   Is   not 
accessed . 

•  Use  ID. EXT  to  extend  the  file. 

C.6.5  Deleting  a  Pile 

To  delete  a  file: 

•  Use  lO.FNA  to  find  the  file  identifier. 

•  Use  lO.RNA  to  remove  the  directory  name. 

•  Use  lO.DEL  to  delete  the  file. 

C.7   ERRORS  RETURNE:!/  BY  THE  FILE  PROCESSORS 

The  error  codes  returned  by  FllACP  and  MTAACP  are  shown  in  Table  r-2. 
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Table  C-2 
File  Processor  Error  Codes 


Error 

Code 

Operations 

Explanation 

I  E.ABO 

'O.RVB/IO.WVB 

Indicates  that  all 
requested  data  was  not 
transferred  by  the 
device. 

lE.ALC 

Extend  or  create  operation 

Indicates  that  the 
operation  failed  to 
allocate  the  file  based 
on  placement  control  or 
because  of  other  related 
problems. 

lE.ALN 

An  attempt  to  access  a  file 

Indicates  that  a  file  is 
already  accessed  on  that 
LUN. 

IE. BAD 

Any  function 

Indicates  that  a  required 
parameter  is  missing, 
that  a  parameter  that 
must  not  be  present  is 
present,  that  a  parameter 
that  must  be  disabled  is 
enabled,  or  that  a 
parameter  value  is 
inval id . 

lE.BDR 

Directory  operations 

Indicates  that  you 
attempted  a  directory 
operation  on  a  file  that 
is  not  a  directory,  or 
that  the  specified 
directory  is  corrupted. 
This  is  usually  caused  by 
.^  0  version  number  field. 

lE.BHD 

Any  operation 

Indicates  i:hat  a  corrupt 
file  header  was 
encountered,  or  that  the 
operatic  required  a 
feature  not  supported  by 
the  FCP  (such  as 
multiheader  support  or 
support  for  unimpiemented 
features) . 

I E .  Bvr? 

Directory  operations 

Indicates  that  you 
attempted  to  enter  a  name 
in  a  directory  with  a 
negative  or  0  version 
number . 

(continued  on  next  page) 
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Table  C-2   (Cent.) 
Pile  Processor  Error  Codes 


Brcoc 

Code 

Operations 

Explanation 

IE. BYT 

Any  function 

This  error  is  returned  if 
the  buffer  specified  is 
on  an  odd  byte  boundary 
or  is  not  a  multiple  of 
four  bytes. 

IB.BTP 

Unlabeled  Magtape  Create 

An  attempt  was  made  to 
create  an  unlabeled  tape 
file  with  a  record  type 
other  than  fixed. 

IB.CKS 

Any  operation 

Indicates  that  the 
checksum  of  a  file  header 
is  incorrect. 

lE.CLO 

Pile  access  operations 

Indicates  that  the  file 
was  locked  against  access 
by  the  "deaccess  lock 
bit." 

lE.OFU 

An  allocation  request 

Indicates  that  there  is 
insufficient  free  disk 
space  for  the  requested 
allocation. 

IB.DUP 

An  enter  name  operation 

Indicates  that  the  name 
and  version  already 
exist. 

IE. EOF 

lO.RVB/IO.WVB/IO.DEL 

On  read  operations,  this 
indicates  an  attempt  to 
read  beyond  end  of  file. 
On  truncate  operations, 
it  indicates  an  attempt 
to  truncate  a  file  to  a 
length  longer  than  that 
allocated  or  that  the 
file  was  already  at  EOF. 

IB.HPU 

An  extended  operation 

Indicates  that  the  file 
header  is  full  and  cannot 
contain  any  more 
retrieval  pointers  and 
that  adding  an  extension 
header  is  not  allowed. 
When  this  is  returned  on 
a  create  operation,  it 
indicates  that  the  index 
file  could  not  be 
extended  to  allow  a  file 
header  to  be  allocated. 

IE. IPC 

Returned  by  exec 

Illegal  function  code. 

(continued  on  next  page) 
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Table  C-2   (Cont.) 
File  Processor  Error  Codes 


Error 

Code 

Operations 

Explanation 

lE.IPU 

Create  or  extend  operation 

Indicates  that  there  are 
no  file  headers  available 
based  on  the  parameters 
specified  when  the  volume 
was  initialized. 

lE.LCK 

Returned  on  file  access. 

Indicates  that  the  file 

directory  operations,  an'i 

is  already  accessed  by  a 

on  truncate 

writer  and  that  shared 
write  has  not  been 
requested  or  Is  not 
allowed . 

lE.LUN 

Any  operation  requiring 

Indicates  that  file  ID 

a  file  ID 

has  not  been  supplied  and 
that  the  file  is  not 
accessed  on  the  LUN. 

IF. NOD 

All  file  operations 

Indicates  that  an  I/O 

that  require  DSR 

request  failed  due  to 
lE.UPN,  that  the  FCP  was 
unable  to  allocate 
required  space  from  DSR 
or  from  secondary  pool 
for  data  structures. 

lE.NSF 

All  file  operations 

Indicates  that  the 
specified  directory  entry 
does  not  exist,  that  a 
file  corresponding  to  the 
file  ID  does  not  exist, 
or  that  the  file  is 
marked  for  delete. 

lE.OFL 

Returned  by  exec 

The  device  is  off  line. 

lE.PRI 

Any  operation 

Indicates  that  the  user 
does  not  have  the 
required  privilege  for 
the  requested  operation, 
or  that  the  user  has  not 
requested  the  proper 
access  to  the  file  if  the 
file  is  already  accessed 
(for  example,  an  attempt 
to  write  to  a  file  that 
is  accessed  for  read). 
This  also  indicates  an 
attempt  to  do  file  I/O  to 
a  device  that  is  not 
mounted . 

(continued  on  next  page) 
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Table  C-2   (Cent.) 
Pile  Processor  Error  Codes 


Error 

Code 

Operations 

Explanation 

lE.RER 

Any  operation 

Indicates  that  the  FCP 
encountered  a  fatal 
device  read  error  during 
an  operation;   the 
operation  has  been 
aborted. 

lE.SNC 

Any  operation 

Indicates  that  the  file 
number  and  the  value 
contained  in  the  header 
do  not  agree.   This 
generally  means  that  the 
header  has  gone  bad  due 
to  a  crash  or  a  hardware 
error. 

lE.SPC 

Returned  by  exec 

Indicates  an  illegal 
buffer. 

lE.SOC 

Any  operation 

Indicates  that  the  file 
sequence  number  does  not 
agree  with  the  file 
header;   usually 
indicates  that  the  file 
has  been  deleted  and  the 
header  has  been  reused. 

lE.WAC 

File  access  operations 

Indicates  that  the  file 
is  already  write  accessed 
and  lock  against  writers 
is  requested. 

IE. WAT 

Write  attributes 

Indicates  that  the  FCP 

and  deaccess 

encountered  an  invalid 
attribute. 

lE.WER 

Any  operation 

Indicates  that  the  "CP 
encountered  a  fatal 
device  write  error  during 
an  operation.   The 
operation  has  been 
aborted  but  the  disk 
structure  may  have  been 
corrupted. 

lE.WLK 

Any  operation 

Indicates  that  the  volume 

requiring  write  access 

is  software  wr i te-locked . 
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A/D  converter,  14-1 

ADOl-D,  14-1 

APCll,  14-1 

device-specific  QIO,  14-2  to 
14-3 

FORTRAN  interface,  14-3  to 
14-7 

standard  QIO,  14-2 

status  return,  14-8  to  14-9 
A/D  gain  range,  14-10 
AAll-K,  22-2 
AAVll-K,  22-2 
ACP 

QIO  interface,  C-1 
ADOl-D,  14-1 
ADll-K,  22-2 
ADVll-K,  22-2 
AFCll,  14-1 
AMll-K,  22-2 
Analog-to-digital  converter 

See  A/D  converter 
Ancillary  Control  Processor 

See  ACP 
ARll,  16-1  to  16-2 
ASR-33,  2-3,  3-2 
ASR-35,  2-3,  3-2 
Assign  LUN 
AST 

service  routine,  1-11,  1-13 

terminating  service,  1-24 

unsolicited- input-character, 
3-32  to  3-33 
ASTX$S,  1-24 

Asynchronous  serial  line 
interface 

DLll,  2-40,  3-30 

DLll-E,  12-2 
Asynchronous  serial  line 
multiplexer 

DHll,  2-40,  3-29 

DHVll,  2-40 

DJll,  2-40,  3-30 

DZll,  2-40,  3-30 
Asynchronous  System  Trap 

See  AST 
Auto-baud  speed  detection,  2-42 
Automatic  carriage  return,  2-34, 
3-27  to  3-28 

Badge  reader,  2-4A,  3-3 
Block  size 

magnetic  tape,  8-14 
Break-through  write,  2-22 
Buffer 

type-ahead,  2-37 


Buffering 

variable-length,  3-28 

Card  input  error 

error  recovery,  11-3 
Card  reader,  11-1 

binary  format,  11-9 

control  character,  11-8 

data  format,  11-9 

data  format  translation,  11-9 

device-specific  QIO,  11-3 

format  translation,  11-10 

indicator  light 

list  of,  11-5  to  11-6 

standard  QIO,  11-2 

switch 

list  of,  11-5  to  11-6 
Card  reader  check 

recovery,  11-4 
Carriage  return 

automatic,  2-34,  3-27  to  3-28 
Cassette,  9-1 

block  length,  9-8 

device-specific  QIO,  9-3 

space  functions,  9-7 

standard  QIO,  9-2 

status  return,  9-3  to  9-5 

structure,  9-6 
Character 

control,  2-27,  2-33 

task-buffering  of  received, 
2-36 

vertical  format  control,  2-34, 
10-6 
Checkpointing 

during  terminal  input,  3-31 
Control  character 

card  reader,  11-8 
list  of,  11-9 

terminal,  2-27,  2-33,  3-20, 
3-25 
Controller 

DECtape,  6-1 

disk 

UDA50,  5-4 
Counter 

initial  value,  18-23  to  18-24 

interrupt 

disconnect,  18-23  to  18-24 
CRll,  11-1 
CTRL/C,  3-20 
CTRL/I,  3-20 
CTRL/J,  3-20 
CTRL/K,  3-20 
CTRL/L,  3-20 
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CTRL/M,  3-20 

CTRL/0,  2-13,  3-21 

CTRL/Q,  3-21 

CTRL/R,  3-21 

CTRL/S,  3-21 

CTRL/U,  3-21 

CTRL/Z,  3-21 

Cursor  control,  2-39,  3-33 

Data  format 

card  reader,  11-9 
DECprinter,  2-4 

LA180,  10-2 
DECtape,  6-1 

device-specific  QIO,  6-3 
recovery  procedure,  6-6 
reversing  direction,  6-7 
select  recovery,  6-7 
standard  QIO,  6-2 
status  return,  6-4  to  6-6 
DECTAPE  II 
See  TU58 
Density  selection 

magnetic  tape,  8-15 
Device 

attaching  to,  1-26 
detaching,  1-27 
logical,  1-18 
null,  19-1 
Device  name 

physical,  1-18  to  1-20 
DHll,  2-40,  3-29 

remote,  3-31 
Diagnostic  function 

user-mode,  1-30 
Dial-up  line,  2-42 
Digital  output 
bistable 

multipoint,  18-18 
multipoint,  18-17 
DIR$  macro,  1-16 
Directive  Parameter  Block 

See  DPB 
Disk 

cartridge 
RK05,  5-3 
RK06,  5-3 
RK07,  5-3 
RL02,  5-3 
emulator 

ML-11,  5-4 
fixed 

RA80,  5-4 
RA81,  5-4 
RD51,  5-4A 
fixed-head 

RFU/RSll,  5-1 
RS03,  5-1 
RS04,  5-1 
fixed/ removable 

RC25,  5-4A 
flexible 
RXOl,  5-4 


Disk 

flexible  (Cont.) 
RX02,  5-4 
RX50,  5-4A 
geometry,  5-2 
last-track,  5-12 
pack 

RA60,  5-4 
RM02,  5-3 
RM03,  5-3 
RM05,  5-3 
RM80,  5-3 
RP02,  5-1 
RP03,  5-1 
RP04,  5-3 
RP05,  5-3 
RP06,  5-3 
power-fail  recovery,  1-39 
removable/ fixed 

RC25,  5-4A 
status  return,  5-8  to  5-11 
Disk  controller 

UDA50,  5-4 
DJll,  2-40,  3-30 
DLll,  2-40,  3-30 

receiver  interrupt  enable, 
3-33 
DMCll,  12-3 
DPll,  12-3 
DPB,  1-13 

diagnostic,  1-31 
previously  defined,  1-16 
QIO,  1-14 
DQll,  12-3 
DRll-K,  22-2 
DRVll,  22-2 
DSS/DRS 

configuration,  18-7 
DSSll,  18-1 

address  assignment,  18-2 
DT07,  23-1 

devlce-specifc  QIO,  23-4  to 

23-6 
FORTRAN  interface,  23-8 
power-fail  recovery,  23-6 
standard  QIO,  23-2  to  23-3 
status  return,  23-7 
DUll,  12-3 
DUPll,  12-4 
DZll,  2-40,  3-30 

remote,  3-31  to  3-32 

End-of-tape 

logical,  9-8 

paper  tape,  17-5 
End-of-volume  status 

magnetic  tape,  8-15  to  8-16 
Escape  code 

conversion,  2-40A,  3-30 
Escape  sequence,  2-29,  3-22 

receiving,  2-32 

syntax  exception,  2-33,  3-26 

syntax  violation,  2-32,  3-24 
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Escap«  saqucnc*  (Cont,) 

VTIOO,  2-31 
Event 

significant,  1-12 
Event  flag 

wait  for,  1-24 

Fixed  and  removable,  single 
spindle  disk,  S-4A 

Format  control 
vertical 

line  printer,  10-5  to  10-6 
terminal,  3-26  to  3-27 

Gain 

A/D,  14-10 
Get  Multiple  Characteristics, 

2-13 
GLUN$,  1-21 

A/D  converter,  14-2 

card  reader,  11-1  to  11-2 

cassette,  9-1  to  9-2 

DECtape,  6-1  to  6-2 

disk,  5-4A 

DT07  UNIBUS  switch,  23-2 

full-duplex  terminal  driver, 

2-6  to  2-7 
graphic  display  driver,  20-1 
half-duplex  terminal  driver, 

3-4  to  3-5 
ICS/ICR,  18-8 
laboratory  peripheral  system, 

16-2 
line  printer,  10-2  to  10-3 
LPAll-K,  21-2 
magnetic  tape,  8-3 
message-oriented 

communication  device, 

12-4 
paper  tape,  17-1 
PCL,  13-2 
table  of  bits  returned,  1-22 

to  1-23 
TU58,  7-1  to  7-2 
UDCll,  15-3 
virtual  terminal,  4-1 
Graphic  display  driver 

device-specific  QIO,  20-2 
standard  QIO,  20-2 
status  return,  20-3 

Hard  receive  error 
detection,  2-36 


I/O 

canceling  request,  1-27 
completion,  1-32 
function  code 
summary,  B-1 
issuing  request,  1-16 
logical,  1-2 
physical,  1-2 


I/O  (Cont.) 

standard  function, 

1-26 
status  block,  1-11 
status  code,  1-33 

summary,  B-1 
status  condition 

table,  1-36  to  1 
virtual,  1-2 
I/O  status  block 
K-series,  22-32 
LPAll-K,  21-30  to 
ICS/ICR,  18-1 

address  assignment 
configuration,  18- 
dev ice- specific  QI 

18-12 
direct  access,  18- 
error  recovery,  18 
FORTRAN  interface, 

18-70 
list  of  supported 

18-3 

standard 

Industrial 

18-1 
Interface 

terminal , 

Interi'upt 

counter 

disconnect,  18-2 
link  task  to,  18 
digital 

connect,  18-20  t 
disconnect,  18-2 
link  task  to,  18 
error 

link  task  to,  18 
terminal 

connect,  18-24 
link  task  to,  18 
unsol icited 

activating  task, 

ICS/ICR  processi 

to  18-20 


QIO,  lb-8 
control  s 


3-2 


1-25  to 
,  1-35 

-38 

21-32 

,  18-2 

7 

0,  18-8  to 

75  to  18-80 
-71 
18-35  to 

module, 

to  18-12 
ubsystem. 


3  to  18-24 
-27 

0  18-21 

1  to  18-23 
-26 

-28 


-28 

18-25 
ng,  18-18 


K-series,  22-1 

buffer  management,  22-32 

FORTRAN  interface,  22-7  to 
22-30 

I/O  status  block,  22-32 

NACRO-11  interface,  22-31 

routine 

generating,  22-4  to  22-5 
Key 

escape,  3-22 

return,  3-22 

rubout,  3-22,  3-24 

special,  2-29 
KSR-33,  2-3,  3-2 
KSR-35,  2-3,  3-2 
KW;i-K,  22-3 
KWVll-A,  22-3 
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LAIOO,  2-3 
LA12,  2-3 
LA120,  2-4,  3-3 
LA180,  10-2 
LA180S,  2-4,  3-3 
LA30,  2-4,  3-2 
LA30-P,  3-29 
LA34,  2-4 
LA36,  2-4,  3-2 
LA38,  2-4 
LA50,  2-4A 
Laboratory  peripheral 

K-series  support  routine, 
22-1 
Laboratory  Peripheral 
Accelerator 

S  e  LPAll-K 
Laboratory  peripheral  system, 
16-1 

clock  rate,  16-33  to  16-34 

device-specific  QIO,  16-3  to 
16-9 

FORTRAN  interface,  16-9 
subroutine  summary,  16-11 

to  16-28 
synchronous  subroutine, 
16-10 

sampling  rate,  16-33  to  16-34 

standard  QIO,  lS-2 

status  return,  16-29  to  16-33 
Laser  printer 

LNOl,  10-2 
Letter-Quality  Printer,  2-4 
Line 

remote,  2-41  to  2-42,  3-31  to 
3-32 
Line  printer 

list  of,  10-1 

LPll,  10-2 

LSll,  10-2 

LVll,  10-2 

ready  recovery,  10-5 

status  return,  10-4  to  10-5 
LNOl,  10-2 
Logical  block 

reading,  l-?« 

writing,  1-29 
Logical  device,  1-18 
Logical  end-of-tape,  9-8 
Logical  I/O,  1-2 
Logical  unit  number,  1-6,  1-17 

changing  assignment,  1-7 

retrieving,  1-21 
Logical  unit  table,  1-6 
LPll,  10-2 
'.PAll-K,  21-1 

22-bit  addressing,  21-36 

buffer  management,  21-32  to 
21-33 

device-specific  QIO,  21-27  to 
21-29 

FORTRAN  interface,  21-2  to 
21-27 


LPAll-K  (Cont.) 

I/O  status  block,  21-30  to 
21-32 

microcode,  21-34  to  21-35 

time-out,  21-35 

unloading  driver,  21-35 
LPSll,  16-1  to  16-2 
L0P02,  2-4 
LSll,  10-2 
LVll,  10-2 

Magnetic  tape,  8-1 

density  selection,  8-15 

device-sp«4cif ic  QIO,   8-4    to 
8-9 

list  of,   8-2 

select  recovery,  8-13 

standard  QIO,  8-4 

status  return,  8-10  to  8-12 
.MCALL  directive,  1-17 
Message  traffic 

low,  12-12 
Message-oriented  communication 

device-specific  QIO,  12-5  to 
12-7 

full-duplex,  12-11 

half-duplex,    12-11 

redundancy  checking,  12-11 

standard  QIO,  12-5 

status  return,  12-8  to  12-10 

transmission  validation, 
12-11 
Message-oriented  communication 

driver,  12-1 
ML-11,  5-4 
Modem,  2-42,  3-32 
Multiplexer 

asynchronous  serial  line, 
2-40,  3-29  to  3-30 

Q  BUS,  2-40 

Null  device,  19-1 
Overlapped  seek,  "=-7 

etroi  conditions,  17-4 
punch,  17-1 
reader,  17-1 
ready  recovery,  17-4 
standard  QIO,  17-2 
status  return,  17-3  to  17-4 
Parallel  Communications  Link 

See  PCL 
Parallel  interface 

DAll-B,  12-2 
PCL 

receiver 

device-speci fc  QIO,  13-9  to 

13-11 
standard  QIO,  13-8 
status  return,  1?-11  to 
13-12 
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PCL    (Cont.) 

transmitter 

d«vic«-sp«clfc  QIO,    13-3   to 

13-5 
standard   QIO,    13-3 
status    return,    13-6   to  13-6 
PCL  11 

Soe   PCL 
PCLll-B,    13-1 
Personal   Printar,    2-4A 
Physical   device  name,    1-10    to 

1-20 
Physical    I/O,    1-2 
Power-fail    recovery,    1-39 

card   reader,    11-4 

DNCll,    12-12 

DT07,    23-6 

ICS/ICR,    18-72 

line  printer,  10-5 

magnetic  tape,  8-14 
Print  line  truncation,  10-7 
Printer 

LA180,  10-2 

LNOl,  10-2 

LPll,  10-2 

LSll,  10-2 

LVll,  10-2 
Process  control 

asynchronous,  14-3,  15-16 

synchronous,  14-3,  15-16 
Pseudo-device 

name,  1-21 
Punched  card,  11-1 

QIO,  1-16 

$C  form,  1-15 

device- independent,  C-1 

device-specific 

A/D  converter,  14-2  to  14-3 
card  reader,  11-3 
cassette,  9-3 
DECtape,  6-3 
disk,  5-7  to  5-8 
DT07,  23-4  to  23-6 
graphic  display  driver, 

20-2 
ICS/ICR,  18-8  to  18-12 
laboratory  peripheral 

system,  16-3  to  16-9 
LPAll-K,  21-27  to  21-29 
magnetic  tape,  8-4  to  8-9 
message- oriented 

communication,  12-5  to 

12-7 
PCL  receiver,  13-9  to  13-11 
PCL  transmitter,  13-3  to 

13-5 
RA80,  5-8 
terminal,  2-8  to  2-10,  3-5 

to  3-6 
TU58,  7-3  to  7-4 
UDCll,  15-3  to  15-9 
virtual  terminal,  4-2,  4-5 


QIC  (Cont.) 
$  form,  1-14 
function  suaaary,  A-1 
■aero  format,  1-9 
$S  form,  1-15 
standard 

A/D  converter,  14-2 
card  reader,  11-2 
cassette,  9-2 
DBCtape,  6-2 
disk,  5-5  to  5-7 
DT07,  23-2  to  23-3 
graphic  display  driver, 

20-2 
ICS/ICR,  18-8  to  18-12 
laboratory  peripheral 

system,  16-2 
line  printer,  10-3 
magnetic  tape,  8-4 
message- oriented 

communication,  12-S 
paper  tape,  17-2 
PCL  receiver,  13-8 
PCL  transmitter,  13-3 
terminal,  2-7 
TU58,  7-2  to  7-3 
UDCll,  15-3 
summary  of  form,  1-14 
virtual  terminal,  4-2 
0IOM$,  1-16 
Queue  I/O  and  Wait 

See  QIOW$ 
Queue  I/O  Request 
See  QIO 

RA60,  5-4 
RA80,  5-4 
RA81,  5-4 
RC2  5,  5-4A 
RD51,  5-4A 
Ready  recovery 

card  reader,  11-4 

paper  tape,  17-4 
Receive  error 

hard,  2-36 
Remote  line,  2-41  to  2-42 

answer  speed,  2-42 

disconnecting,  2-23 
Removable  and  fixed,  single 

spindle  disk,  5-4A 
RFll/RSll,  5-1 
RK05,  5-3 
RK06,  5-3 
RK07,  5-3 
RL02,  5-3 
RM02,  5-3 
RM03,  5-3 
RM05,  5-3 
RM80,  5-3 
RP03,  5-1 
RP04,  5-1,  5-3 
RP05,  5-3 
RP06,  5-3 
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RS03,  5-1 
RS04,  5-1 
RT02,  2-4A,  3-3 
RT02-C,  3-3 

control  function,  2-40A,  3-30 
RUBOUT,  3-24 

line  printer,  10-6 
RXOl,  5-4 
RX02,  5-4 
RX50,  5-4A 

Seek 

overlapped,  5-7 
Select  recovery 

magnetic  tape,  8-13 
Significant  event,  1-12 
Speed  detection 

auto-baud,  2-42 
SST,  1-12 
Status  block 

I/O,  1-35 
Status  code 

I/O,  1-33,  B-1 
Status  return 

A/D  converter,  14-8  to  14-9 

card  reader,  11-3,  11-7 

cassettfa,  9-3  to  9-5 

DECtape,  6-4  to  6-6 

disk,  5-8  to  5-11 

DT07,  23-7 

graphic  display  driver,  20-3 

ICS/ICR,  18-13  to  18-14 

laboratory  peripheral  system, 
16-29  to  16-33 

line  printer,  10-4  to  10-5 

magnetic  tape,  8-10  to  8-12 

message- oriented 

communication,  12-8  to 
12-10 

paper  tape,  17-3  to  17-4 

PCL  receiver,  13-11  to  13-12 

PCL  transmitter,  13-6  to  13-8 

terminal,  2-23  to  2-27 

TU58,  7-4  to  7-5 

UDC,  15-32  to  15-34 
Synchronous  line  interface 

DMCll,  12-3 

DPll,  12-3 

DQU,  12-3 

DUll,  12-3 

DUPll,  12-4 
Synchronous  System  Trap 

See  SST 


TAll,  9-1 

TCll-0,  6-1 

Teletype,  2-3,  3-2 

Terminal 

attaching,  2-12  to  2-13 
control  character,  2-27  to 

2-29 
desk-top,    2-3 


Terminal    (Cont.) 

device-specific   QIC,    2-8,    3-5 
to  3-6,    3-8 

escape    sequence,    2-29 

escape   sequence   recoanition, 
2-13 

full-duplex,    2-14 

full-duplex   operation,    2-38 

graphics,   2-5 

half-dupleK,  3-1 

interface,  2-39 

portable,  2-3 

QIC  subfunction  bit,  2-9 

special  key,  2-30  to  1   31 

standard  interfaces,  3-2 

standard  QIO  function,  2-7 

status  return,  2-23  to  2-27 

subfunction,  3-7,  3-9 

subfunction  summary,  2-11 

teletype.  2-3 

t'pe,  2-17 

virtual,  4-1 
Terminal  characteristics,  2-13 
to  2-15 

setting,  2-21 

side  effects,  2-41,  3-32 

virtual  terminal,  4-6 
Tern  inal  driver 

loadable,  3-33 

virtual,  4-1 
Terminal  line  truncation,  3-30 
Trap 

system,  1-12 
Truncation 

print  line,  10-7 

terminal  line,  3-30 
TU58,  7-1 
Type-ahead,  2-3  7 

UDA50,  5-4 
UDC,  15-1 

device-specific  QIO,  15-3  to 
15-9 

direct  access,  15-10 

FORTRAN  interface,  15-15 

FORTRAN  subroutine  summary, 
15-17  to  15-31 

standard  QIO,  15-3 

status  return,  15-32  to  15-34 
UDCll,  15-1,  18-3 
UMDIO$,  1-31 
UN I BUS 

power-fail  recovery,  23-6 
UNIBUS  switch,  23-1 
Universal  digital  controller 

See  UDC 
Unlabeled  tape,  8-15  to  8-16 
User-mode  diagnostic  function, 
1-30 

Vertical  format  control 

line  printer,  10-5  to  10-6 
terminal,  2-33,  3-26  to  3-27 
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Virtual  block 

reading,  1-28 

writing,  1-29 
Virtual  I/O,  1-2 
Virtual  terminal,  4-1 

devict-specif ic  QIO,  4-2,  4-5 
VS60,  20-1 
VT05B,  2-5,  3-3 
VTIOO,  2-5,  3-4 

escape  sequence  format,  2-31      Write 
VTlOl,  2-6  break-through,  2-22 

VT102,  2-6  WTSE$,  1-24 


VT105, 

,  2-6 

VTll, 

20-1 

VT131, 

,  2-6 

VT50, 

2-5, 

3-3 

VT50H, 

r  2-5, 

-  3-3 

VT52, 

2-5, 

3-4 

VT55, 

2-5, 

3-4 

VT61, 

2-5, 

3-4 
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